Ember CLI Mirage

Common errors

• Module not found: Error: Can't resolve 'miragejs'

  cause The `miragejs` package is a peer dependency since `ember-cli-mirage@3.x` but has not been installed.
  fix Run `npm install miragejs` or `yarn add miragejs` to add the core library to your project's dependencies.

• TypeError: (0 , ember_cli_mirage__WEBPACK_IMPORTED_MODULE_2__.Server) is not a constructor

  cause Attempting to instantiate `Server` from `ember-cli-mirage` in `mirage/config.js`, which was removed in v3.0.0-alpha.2.
  fix Change your `mirage/config.js` to import `createServer` from `miragejs` and call it with your config function: `import { createServer } from 'miragejs'; export default function() { createServer({ environment: 'test', routes() { /* ... */ } }); }`.

• TypeError: Cannot read properties of undefined (reading 'schema') in MirageJS

  cause This often occurs when `this.server.create(...)` or `this.server.schema(...)` is called outside the context where Mirage's server is properly initialized, such as within a test hook but before `setupMirage` has run, or in an incorrect context.
  fix Ensure `setupMirage(hooks)` is called for the current test module, and that any server interactions are within `beforeEach`, `afterEach`, or `test` blocks where `this.server` is guaranteed to be available.

Warnings

• breaking `miragejs` is now a peer dependency and must be explicitly installed. This means you need to add `npm install miragejs` to your project.
  Fix: Run `npm install miragejs` (or `yarn add miragejs`) in your project root after upgrading to `ember-cli-mirage@3.x`.
• breaking The `ember-cli-mirage` Server class has been removed. You must now use `createServer` imported directly from `miragejs` in your `mirage/config.js`.
  Fix: Update your `mirage/config.js` to use `import { createServer } from 'miragejs';` and pass your config to it, instead of instantiating `Server` directly from `ember-cli-mirage`.
• breaking Deprecated re-exports from `ember-cli-mirage` (like `Response`, `Factory`, `Model`, etc.) which were originally from `miragejs` have been removed. You must import these directly from `miragejs`.
  Fix: Replace `import { Response } from 'ember-cli-mirage/response';` (and similar re-exports) with `import { Response } from 'miragejs';`.
• breaking Support for older Ember.js and Node.js versions has been dropped. `ember-cli-mirage@3.x` requires Ember.js v3.28+ and Node.js v16+.
  Fix: Ensure your project meets the minimum requirements: upgrade Ember.js to 3.28 or higher and Node.js to 16 or higher. Run `npx ember-cli-update` for assistance.
• gotcha In a testing environment, `setupMirage(hooks)` should be called to properly initialize the Mirage server for each test module. For acceptance tests, `setupApplicationTest(hooks)` also initializes Mirage if configured.
  Fix: Always include `setupMirage(hooks);` within your QUnit or Mocha `module()` setup function for tests that interact with Mirage.

Install

• npm install ember-cli-mirage npm
• yarn add ember-cli-mirage yarn
• pnpm add ember-cli-mirage pnpm

Imports

• setupMirage
  wrong:

  import { setupMirage } from 'ember-cli-mirage';

  correct:

  import { setupMirage } from 'ember-cli-mirage/test-support';

  This helper is specifically for test setups and is imported from `test-support`. Available since v3.0.0-alpha.3 with TypeScript declarations.
• createServer
  wrong:

  import { Server } from 'ember-cli-mirage'; new Server(...);

  correct:

  import { createServer } from 'miragejs';

  Since v3.0.0-alpha.2, you must import `createServer` directly from `miragejs` and use it within your `mirage/config.js`. The `ember-cli-mirage` Server class was removed.
• Response
  wrong:

  import Response from 'ember-cli-mirage/response';

  correct:

  import { Response } from 'miragejs';

  For custom HTTP responses, `Response` should be imported directly from `miragejs`. Re-exports from `ember-cli-mirage` were removed in v3.0.0-alpha.1.

Quickstart

This quickstart demonstrates how to install `ember-cli-mirage`, define basic mock API routes in `mirage/config.js`, and integrate `setupMirage` into an Ember QUnit test to provide mock data.

import Application from '@ember/application';
import config from './config/environment';
import loadInitializers from 'ember-load-initializers';

// app/mirage/config.js
// This file is automatically loaded by ember-cli-mirage.
// It's where you define your API routes, factories, and serializers.
export default function() {
  this.get('/posts', function(schema, request) {
    return schema.posts.all();
  });

  this.post('/posts', function(schema, request) {
    let attrs = JSON.parse(request.requestBody);
    return schema.posts.create(attrs);
  });

  this.passthrough('/users/**'); // Example of proxying requests
}

// tests/test-helper.js (example usage in a test)
import resolver from './helpers/resolver';
import { setApplication } from '@ember/test-helpers';
import { start } from 'ember-qunit';
import { setupMirage } from 'ember-cli-mirage/test-support';

setApplication(Application.create(config.APP));

module('Integration | Component | my-component', function(hooks) {
  setupApplicationTest(hooks);
  setupMirage(hooks); // This will start Mirage for your tests

  test('it renders posts', async function(assert) {
    this.server.createList('post', 3); // Create some mock data
    await render(hbs`<MyComponent />`);
    assert.dom('.post').exists({ count: 3 });
  });
});