1.0.9 • Public • Published

API twins mock server

There are a lot of mock servers/clients out there. Wire-mock, VCR, you name it.

API TWINS tries to solve the biggest dilemma of frontend-backend testing:

  • Use real backend to feed frontend with real replies
  • Use mocked backend

Both approaches have serious downsides:

  • Its difficult to get the backend to the state required for a particular test
  • Mocks start to drift from the current backend implementation

How does API TWINS approach work in general?

  1. Backend tests generate files with "canned" HTTP requests
  2. api_twins_server loads all files generated on step #1
  3. Frontend tests make requests to api_twins_server

API TWINS works best with Use cases. Look how "canned" request are stored.

├── _default
│   └── GET_api_embed_v1_loader.v001.js.json
├── _manual
│   ├── GET_api_insecure_v1_options.json
│   ├── OPTIONS_api_embed_v1_check.json
│   └── OPTIONS_api_embed_v1_send.json
└── embed_mode_2
    ├── [user_exists]_GET_api_forms_v1_form.json
    ├── [user_exists]_POST_api_embed_v1_check.json
    ├── [user_exists]_POST_api_embed_v1_send.json
    ├── [user_exists]_POST_api_embed_v1_token.json
    ├── [user_exists]_POST_api_forms_v1_form.json
    ├── [user_absent]_POST_api_embed_v1_send.json
    └── [user_absent]_POST_api_forms_v1_form.json
  • embed_mode_2 -- use case name
  • user_exists, user_absent -- use case path (extension in terms of use case theory)
  • _default -- "cans" for all use cases
  • _manual -- the only place where you can put your manual written "cans". Files in other directories are created by backend tests

"Can" file format

JSON file:

    "method": "POST",                        # Method
    "url": "/api/embed/v1/send",             # Endpoint pathname
    "query": {                               # Query string parameters
        "seriesId": "8",
        "mode": "2"
    "body": {                                # Request body parameters
        "phone": "9000000",
        "code": "0000"
    "status": 404,                           # HTTP response code (default: 200)
    "reply": {                               # Server reply
        "key1": "value1",
        "key2": "value2"
    "replyHeaders": {                        # Headers to be set by server
        "Content-Type": "application/json"

How api_twins_server matches requests with responses

  • use case name and use case path match
    • if not found search repeats with _default and _manual use case name and empty use case path
  • url (enpoint pathname) matches
  • method matches
  • all body entries listed in "can" file are equal
  • all query entries listed in "can" file are equal

In order to match the request sent to api_twins_server must have all input parameters present in the "can" file and may have any additional parameters.

How api_twins_server knows which of the use cases/path to use?

There is no magic here. Frontend tests have to set the use case/path name during test setup. There are options:

  • Cookie. The simpliest one as cookie is glued into all requests automatically and no code change is required
document.cookie = 'api_twin=embed_mode_2:user_exists; path=/'
  • Get parameter. Add ?api_twin=embed_mode_2:user_exists to all requests you want to mock

  • Header. Add X-Api-Twin: embed_mode_2:user_exists header to all requests you want to mock

How to change some parameters?

All parameters are passed with environment:

  • PUBLIC -- api_twins_server can work as server for static assets (images, JS bundls, etc.). PUBLIC environment variable has to be set to some filesystem path in order to server enable this feature
  • PUBLIC_PATH -- webserver path to the static assets (/ by the default).
  • PORT -- server port (3000 by the default)
  • TWINS_PATH -- directory where API TWINS files are located (./api_twins by the default).



Package Sidebar


npm i api_twins_server

Weekly Downloads






Unpacked Size

35.8 kB

Total Files


Last publish


  • maxsivanov