Configuration

Besides defining your routes, there’s some config options for your server available in mirage/config.js. There’s also some environment options, which you define in /config/environment.js.

Server config

Note that this within your config function in mirage/config.js refers to the server instance, which is the same instance that server refers to in your tests.

# this.namespace

Set the base namespace used for all routes defined with get, post, put or del.

For example,

// mirage/config.js
export default function() {

  this.namespace = '/api';

  // this route will handle the URL '/api/contacts'
  this.get('/contacts', 'contacts');
};

Note that only routes defined after this.namespace are affected. This is useful if you have a few one-off routes that you don’t want under your namespace:

// mirage/config.js
export default function() {

  // this route handles /auth
  this.get('/auth', function() { /* ... */});
  
  this.namespace = '/api';
  // this route will handle the URL '/api/contacts'
  this.get('/contacts', 'contacts');
};

If your Ember app is loaded from the filesystem vs. a server (e.g. via Cordova or Electron vs. ember s or https://yourhost.com/), you will need to explicitly define a namespace. Likely values are / (if requests are made with relative paths) or https://yourhost.com/api/... (if requests are made to a defined server).

For a sample implementation leveraging a configured API host & namespace, check out this issue comment

# this.timing

Set the timing parameter of the response. Default is a 400ms delay during development and 0 delay in testing (so your tests run fast).

// mirage/config.js
export default function() {

  this.timing = 400; // default

};

Note that this is a global parameter which affects all routes. You can override the timing for individual routes by using the route handler’s timing parameter.

If you want to add delays to a particular test’s routes, you can override the timing for individual tests by putting the timing parameter in your test

test('Call this route with a delay', function() {
  server.timing = 10000;
  // ...
});

Or for all tests in a particular module

module('Add delayed route calls to multiple tests', function() {
  server.timing = 10000;
  
  test('It slowly calls a route', function() {
    // ...
  });
  
  test ('It slow calls another route', function() {
    // ...
  });
});

# this.logging

Set to true or false to explicitly specify logging behavior.

By default, server responses are logged in non-testing environments. Logging is disabled by default in testing, so as not to clutter CI test runner output.

For example, to enable logging in tests, write the following:

test('I can view all users', function() {
  server.logging = true;
  server.create('user');
  
  visit('/users');
  // ...
});

You can also write a custom log message, using the Pretender server’s handledRequest hook. See Mirage’s default implementation for an example.

To override,

// mirage/config.js
export default function() {
  this.pretender.handledRequest = function(verb, path, request) {
    let { responseText } = request;
    // log request and response data
  }
}

# this.passthrough(path1, path2…, options)

By default, if your Ember app makes a request that is not defined in your server config, Mirage will throw an error. You can use passthrough to whitelist requests, and allow them to pass through your Mirage server to the actual network layer.

To ignore paths on your current host (as well as configured namespace), use a leading /:

this.passthrough('/addresses');

You can also pass a list of paths, or call passthrough multiple times:

this.passthrough('/addresses', '/contacts');
this.passthrough('/something');
this.passthrough('/else');

These lines will allow all HTTP verbs to pass through. If you want only certain verbs to pass through, pass an array as the last argument with the specified verbs:

this.passthrough('/addresses', ['post']);
this.passthrough('/contacts', '/photos', ['get']);

If you want all requests on the current domain to pass through, simply invoke the method with no arguments:

this.passthrough();

Note again that the current namespace (i.e. any namespace property defined above this call) will be applied.

You can also allow other-origin hosts to passthrough. If you use a fully-qualified domain name, the namespace property will be ignored. Use two * wildcards to match all requests under a path:

this.passthrough('http://api.foo.bar/**');
this.passthrough('http://api.twitter.com/v1/cards/**');

In versions of Pretender prior to 0.12, passthrough only worked with jQuery >= 2.x. As long as you’re on Pretender@0.12 or higher, you should be all set.

# this.loadFixtures(file1, file2…)

By default, all the data files under /fixtures will be loaded during testing if you don’t have factories defined, and during development if you don’t have /scenarios/default.js defined. You can use loadFixtures() to also load fixture files in either of these environments, in addition to using factories to seed your database.

server.loadFixtures() loads all the files, and server.loadFixtures(file1, file2...) loads selective fixture files.

For example, in a test you may want to start out with all your fixture data loaded:

test('I can view the photos', function() {
  server.loadFixtures();
  server.createList('photo', 10);

  visit('/');

  andThen(() => {
    equal( find('img').length, 10 );
  });
});

or in development, you may want to load a few reference fixture files, and use factories to define the rest of your data:

// scenarios/default.js
export default function(server) {
  server.loadFixtures('countries', 'states');

  let author = server.create('author');
  server.createList('post', 10, {author_id: author.id});
}

# this.pretender

Mirage uses pretender.js as its xhttp interceptor. In your Mirage config, this.pretender refers to the actual Pretender instance, so any config options that work there will work here as well. By default, content returned is json stringified, so you can just return js objects.

Refer to Pretender’s docs if you want to change this or any other options on your Pretender instance.

# testConfig

Export a named testConfig function to define routes that only apply in your test environment:

// mirage/config.js

export default function() {
  // normal config, shared across development + testing
}

export function testConfig() {
  // test-only config, does not apply to development
}

This could be useful if you’d like to use Mirage in testing, but generally proxy to an actual API during development. As you develop, your frontend may be ahead of your API, in which case you’d work with the routes in the default config, and write your tests. Then, once your API implements the new endpoints, you can move the routes to your testConfig, so your tests still run, but Mirage doesn’t interfere during development.

Environment options

Set these options via the ENV['ember-cli-mirage'] variable in your config/environment.js file:

// config/environment.js
...
if (environment === 'production') {
  ENV['ember-cli-mirage'] = {
    enabled: true
  };
}

# enabled

By default, your Mirage server will run in test mode, and in development mode as long as the --proxy option isn’t passed. To change this default behavior, set enabled to either true or false in your ENV config.

For example, to enable in production (e.g. to share a working prototype before your server is ready):

// config/environment.js
...
if (environment === 'production') {
  ENV['ember-cli-mirage'] = {
    enabled: true
  };
}

To disable in development,

// config/environment.js
...
if (environment === 'development') {
  ENV['ember-cli-mirage'] = {
    enabled: false
  };
}

# excludeFilesFromBuild

Defaults to false.

By default, Mirage’s files are included in your Ember app’s build in non-production environments. This is in case you want to use Mirage via ember serve by visiting /tests, since that’s an app with a build-time environment of development but a run-time environment of test.

You can explicilty exclude Mirage’s files from your Ember app’s build by setting excludeFilesFromBuild to true.

# useDefaultPassthroughs

Defaults to true.

If true, Mirage will add some default passthrough routes to your server. Currently we add a single route

• http://localhost:0/chromecheckurl

which is used by iOS for URL verification.

# directory

Configure which directory contains your Mirage server definition. The default directory is /mirage (from the root of your project).

For example, to have your server definition under /mirage,

// config/environment.js
...
ENV['ember-cli-mirage'] = {
  directory: 'mirage'
};