Migrating from v1 to v2

Preface

Mocks Server v2.x introduced the concept of "route variants", and made more restrictive the way for organizing mocks and routes files. It also introduced other improvements, as the possibility of using express middlewares, made simpler the core API, etc.

All of these changes made very difficult to handle old v1 behaviors and fixtures together with the new format of routes, so, in order to maintain backward compatibility, Mocks Server v2 can handle two folders at a time, one containing v1.x fixtures and behaviors, and another one containing v2.x mocks and routes.

This was made with the intention of allowing users to migrate progressively from v1.x format to v2.x format. You can convert old fixtures and behaviors into new mocks and routes and move them from one folder to another, until you have no more legacy code, and you can deactivate the legacy folder.

info

When the same route is defined in v2.x "routes" and v1.x "fixtures", the "fixture" will be ignored, and the "route" will handle the request.

Step by step

Update and enable legacy mode

• First of all, rename your old mocks folder into mocks-legacy
• Install the v2.x version of Mocks Server. npm i --save-dev @mocks-server/main@2.x
• Start Mocks Server. npm run mocks (we suppose you have already your mocks script configured in the package.json). Now you would have a folders structure like:

project-root/
├── mocks-legacy/
│   └── ...
├── mocks/
│   ├── routes/
│   │   └── users.js
│   └── mocks.json
├── mocks-server.config.js
└── mocks.config.js

• Migrate your old options from the mocks-server.config.js file to mocks.config.js (See legacy options below to check the options correspondence). Once done, you can delete the mocks-server.config.js file.
• Enable legacy folder in the configuration to use both folders:

// mocks.config.js

module.exports = {
  options: {
    path: "mocks",
    port: 3100,
    mock: "base",
    watch: true,
    cli: true,
    behavior: "foo-behavior", //migrated from mocks-server.config.js
    pathLegacy: "mocks-legacy", // enables the usage of v1 path
    watchLegacy: true // enables the watch in the v1 path
  }
};

Now, when the interactive CLI is started, settings and actions related with legacy mode will be displayed also:

Migrating fixtures

After reading the v2.x routes and mocks documentation, you would have noticed that old fixtures having the same "path" can be easily migrated to a new route.

For example, old fixtures like:

// mocks-legacy/fixtures/users.json
[
  {
    "id": "get-user",
    "url": "/api/users/:id",
    "method": "GET",
    "response": {
      "status": 200,
      "body": {
        "id": 1,
        "name": "John Doe"
      }
    }
  },
  {
    "id": "get-user-error",
    "url": "/api/users/:id",
    "method": "GET",
    "response": {
      "status": 400,
      "body": {
        "message": "Server error"
      }
    }
  }
]

Can be migrated to a route like:

// mocks/routes/users.json
[
  {
    "id": "get-user",
    "url": "/api/users/:id",
    "method": "GET",
    "variants": [
      {
        "id": "success",
        "response": {
          "status": 200,
          "body": {
            "id": 1,
            "name": "John Doe"
          }
        }
      },
      {
        "id": "error",
        "response": {
          "status": 400,
          "body": {
            "message": "Server error"
          }
        }
      }
    ]
  }
]

Migrating behaviors

Continuing with the previous example, once you have migrated your "fixture" to a "route", you can add it to a new "mock".

If your "behavior" was defined like:

// mocks/behaviors.json
[
  {
    "id": "base",
    "fixtures": ["get-user"]
  },
  {
    "id": "user-error",
    "fixtures": ["get-user-error"]
  },
]

You can define a mock like:

// mocks/mocks.json
[
  {
    "id": "base",
    "routesVariants": ["get-user:success"]
  },
  {
    "id": "user-error",
    "from": "base",
    "routesVariants": ["get-user:error"]
  }
]

info

You would normally have several fixtures in each "behavior". So don't delete the "behavior" until you have migrated all of the "fixtures" that it contains. Simply remove the migrated fixtures from it and let the rest. Mocks Server will use "routes" with priority, but when a request does not match any of them, it will fallback to "fixtures", so you can migrate them progressively.

Legacy options

Next options should be used only for backward compatibility with v1.x, and will be removed in next major version:

• pathLegacy (String): Path to the folder containing legacy v1.x behaviors and fixtures. Correspondent to path in v1.x.
• watchLegacy (Boolean): Disables files watch on legacy path. When used as command line argument, now it has to be negated as no-watch. Correspondent to watch in v1.x.
• behavior (String): Default selected behavior when server is started.

Legacy API

Next mocksServer methods and getters are provided only for backward compatibility, and will be removed in next major version:

• onChangeLegacyMocks(callback): Add a callback to be executed when mocks collections (fixtures or behaviors) changes. Returns a function for removing the added callback.
  • callback(): <Function>
• addFixturesHandler(FixturesHandler): Add a custom fixtures handler. This allows to add new formats or methods of defining fixtures.
  • FixturesHandler: <Class> Custom fixtures handler. Read v1.x versions docs for further info.
• behaviors: Returns methods and getters related to currently available behaviors.
  • count: Getter returning total number of behaviors available.
  • collection: Collection of behaviors instances.
  • ids: Getter returning an array with all behaviors ids.
  • current: Getter returning current active behavior.
  • currentId: Getter returning the id of the current active behavior.
• fixtures: Returns methods and getters related to currently available fixtures.
  • count: Getter returning total number of fixtures available.
  • collection: Collection of fixtures instances.

Legacy plugins methods

• loadLegacyMocks(definitions): New method added for backward compatibility. loadMocks now can be used only to load v2.x mocks.

Breaking changes

Some options and methods that were already deprecated in v1.x have been definitively removed in v2.x.

Misc

• config file: Config file has been renamed from mocks-server.config.js to mocks.config.js

Options

• features: Removed. Legacy pathLegacy option should be used instead.
• behaviors: Removed. Legacy pathLegacy option should be used instead.
• feature: Removed. Legacy behavior option should be used instead.

API

• addSetting(customSetting) The method is still valid, but type property in customSetting does not accept booleanString as value any more. Now boolean type should be used instead.
• onLoadMocks(callback). Removed. onChangeMocks should be used instead (or onChangeLegacyMocks to listen for changes in legacy behaviors or fixtures).
• onLoadFiles. Removed. There is no alternative, as it is an internal event of the files-loader plugin and it shouldn't be used by other external pieces.
• addCustomRouter. Removed. addRouter should be used instead.
• addCustomSetting. Removed. addSetting should be used instead.
• serverError. Removed. alerts should be used instead, because the server now adds an alert when there is an unexpected error.
• restart. Removed. restartServer should be used instead.
• server: This object is still available, but next the getter has been removed from it:
  • features: Removed. Legacy behaviors has to be used instead