Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update v3 upgrade guide #2546

Merged
merged 2 commits into from
Oct 4, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -40,31 +40,6 @@ if (environment === 'development') {
}
```

## trackRequests

A boolean that controls whether [Pretender's `trackRequests` feature](https://github.com/pretenderjs/pretender#tracking-requests) is enabled. By default it is disabled to avoid memory issues during long development sessions.

This should be set in the `mirage/config.js` options. Defaults to `false`.

```js
export default function(config) {
let finalConfig = {
...config,
trackRequests: true,
models: {
...discoverEmberDataModels(config.store),
...config.models
},
routes,
};

return createServer(finalConfig);
}
```

This feature is useful for asserting against HTTP requests and responses during tests. See the "Asserting against handled requests and responses" section of the {{docs-link 'Assertions guide' 'docs.testing.assertions'}} to learn more.


## excludeFilesFromBuild

Defaults to `false`.
Expand Down Expand Up @@ -96,19 +71,3 @@ ENV['ember-cli-mirage'] = {
directory: 'app/mirage'
};
```

## discoverEmberDataModels

Tells Mirage whether to automatically infer its schema from the host application's Ember Data models and relationships.

Defaults to true. If Ember Data models are present, predefines Mirage's models and relationships. If Ember Data models are not present, has no effect.

You can disable by setting to `false`. You might want to do this if you run into an edge case/issue where the autodiscovery code causes issues in your app's environment (for example, if you have a complex engines setup).

```js
// config/environment.js
...
ENV['ember-cli-mirage'] = {
discoverEmberDataModels: false
};
```
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,6 @@ test('I can create a movie', async function(assert) {
});
```

You can view the rest of the Database APIs in the {{docs-link 'Db' 'docs.api.item' 'modules/db~Db'}} and {{docs-link 'DbCollection' 'docs.api.item' 'modules/db-collection~DbCollection'}} API reference.
You can view the rest of the Database APIs in the <a href="https://miragejs.com/api/classes/db/">Db</a> and <a href="https://miragejs.com/api/classes/db-collection/">DbCollection</a> API reference.

Next, we'll learn about Mirage's ORM.
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@ Calling `server.createList('user', 3)` with this factory would generate this dat

### Relationships

In the same way that you use the ORM to create relational data, as this example from the _Creating and editing related data_ section of the {{docs-link 'ORM guide' 'docs.data-layer.orm'}} illustrates
In the same way that you use the ORM to create relational data, as this example from the _Creating and editing related data_ section of the <DocsLink @route="docs.data-layer.orm">ORM guide</DocsLink> illustrates

```js
let nolan = schema.people.create({ name: 'Christopher Nolan' });
Expand Down Expand Up @@ -647,7 +647,7 @@ In this test, we start our Mirage server out with 5 movies. Then we boot up the

When we write another test, the database will start out empty so that none of Mirage's state leaks across tests.

You can read more about testing with Mirage in the {{docs-link 'Testing' 'docs.testing.acceptance-tests'}} section of these guides.
You can read more about testing with Mirage in the <DocsLink @route="docs.testing.acceptance-tests">Testing</DocsLink> section of these guides.


## Factory best practices
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ schema.blogPosts.where({ isPublished: true });
schema.blogPosts.findBy({ title: 'Introduction' });
```

Check out the {{docs-link 'Schema API docs' 'docs.api.item' 'modules/orm/schema~Schema'}} to see all available query methods.
Check out the <a href="https://miragejs.com/api/classes/schema/">Schema API docs</a> to see all available query methods.


## Updating and deleting models
Expand All @@ -102,7 +102,7 @@ let post = schema.blogPosts.find(2);
post.destroy();
```

View the {{docs-link 'Model API docs' 'docs.api.item' 'modules/orm/model~Model'}} to see all the available fields and methods for model instances.
View the <a href="https://miragejs.com/api/classes/model/">Model API docs</a> to see all the available fields and methods for model instances.

---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -206,7 +206,7 @@ user.thingIds = [ { id: 2, type: 'watch' }, ... ];

---

Be sure to check out the {{docs-link 'Schema' 'docs.api.item' 'modules/orm/schema~Schema'}}, {{docs-link 'Model' 'docs.api.item' 'modules/orm/model~Model'}} and {{docs-link 'Collection' 'docs.api.item' 'modules/orm/collection~Collection'}} API docs to learn about all the available ORM methods.
Be sure to check out the <a href="https://miragejs.com/api/classes/schema/">Schema</a>, <a href="https://miragejs.com/api/classes/model/">Model</a> and <a href="https://miragejs.com/api/classes/collection/">Collection</a> API docs to learn about all the available ORM methods.

We'll also cover Serializers in these guides, where you'll learn how to customize the serialized forms of your models and collections to match your production API.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,6 @@ export default EmberDataSerializer.extend({
```

If you would like Mirage to apply the transforms from your ember data serializers for you see
{{docs-link 'Advanced Configuration of Serializers' 'docs.advanced.server-configuration'}}.
<DocsLink @route="docs.advanced.server-configuration">Advanced Configuration of Serializers</DocsLink>.


Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ If you are starting a new app, it's recommended that you choose a JSON:API imple

If your app does use JSON:API, Mirage ships with a `JSONAPISerializer` that will do the heavy lifting for you.

Mirage also ships with two other named serializers, `ActiveModelSerializer` and `RestSerializer`, that match two other popular backend formats. `EmberDataSerializer` is also provided as a variation to the `RestSerializer` that uses the `primaryKey` and `attrs` defined in your applications ember data serializers, similar to how models are auto discovered. See the section on {{docs-link 'Ember Data Serializer' 'docs.data-layer.serializers.ember-data-serializer'}} for more information.
Mirage also ships with two other named serializers, `ActiveModelSerializer` and `RestSerializer`, that match two other popular backend formats. `EmberDataSerializer` is also provided as a variation to the `RestSerializer` that uses the `primaryKey` and `attrs` defined in your applications ember data serializers, similar to how models are auto discovered. See the section on <DocsLink @route="docs.data-layer.serializers.ember-data-serializer">Ember Data Serializer</DocsLink> for more information.

If your backend uses a different format, you'll need to choose the closest one and customize it to match your production format. We'll talk about that later in this guide.

Expand Down Expand Up @@ -250,6 +250,6 @@ In general, you should not need to write much code dealing with Mirage serialize

The more conventional your backend API is, the less code you'll need to write – not only in Mirage, but also in other parts of your Ember application!

Be sure to check out the {{docs-link 'Serializer' 'docs.api.item' 'modules/serializer~Serializer#keyForAttribute'}} and {{docs-link 'JSONAPISerializer' 'docs.api.item' 'modules/serializers/json-api-serializer~JSONAPISerializer'}} docs to learn about all the hooks available to customize your serializer layer.
Be sure to check out the <a href="https://miragejs.com/api/classes/serializer/#key-for-attribute">Serializer</a> and <a href="https://miragejs.com/api/classes/jsonapi-serializer/">JSONAPISerializer</a> docs to learn about all the hooks available to customize your serializer layer.

Now that we've covered the ins and outs of Mirage's data layer, we're ready to see how we can use Mirage to effectively test our Ember application.
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ ember install ember-cli-mirage
Ember should install the addon and add a `/mirage` directory to the root of your project.
Ember-cli-mirage depends on [MirageJS](https://miragejs.com/) as a peer dependency and will add it to your applications `package.json`.

Check out the {{docs-link 'upgrade guide' 'docs.getting-started.upgrade-guide'}} if you're coming from a previous version of Mirage.
Check out the <DocsLink @route="docs.getting-started.upgrade-guide">upgrade guide</DocsLink> if you're coming from a previous version of Mirage.

## Note for Embroider users

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,19 @@ You can view all of Mirage's release notes on [our Releases page](https://github

## 3.0 Upgrade guide

### 1. Update import paths

Ensure that all the imports are updated for the objects that were moved to MirageJS.
This is generally the imports in the files in the mirage directory.

```js
// from
import { Model } from 'ember-cli-mirage';
//to
import { Model } from 'miragejs';
```diff
- import { Model } from 'ember-cli-mirage';
+ import { Model } from 'miragejs';
```

Previous the file `mirage/config.js` was a exported default function that defined only your routes.
### 2. Update default export in `mirage/config.js`

Previously, the file `mirage/config.js` was exporting default function that defined only your routes.
Since MirageJS has been extracted into its own repo, we want to follow the way a server is made in MirageJS.

Change the routes function to no longer be exported as the default function and give it a name, we
Expand Down Expand Up @@ -57,12 +59,57 @@ function routes() {
}
```

The environment variable discoverEmberDataModels is no longer used. If you wish to
not have `ember-cli-mirage` auto discover the models, just remove the `...discoverEmberDataModels(config.store),`
### 3. Remove `testConfig` function

Exporting `testConfig` function from `mirage/config.js` is not supported.
If you need to separate development routes from testing, you can now use
[`@embroider/macros`](https://www.npmjs.com/package/@embroider/macros) package:

```diff
- export function testConfig () {
- }
+ function routes() {
+ if (macroCondition(isTesting())) {
+ testRoutes.call(this);
+ } else {
+ devRoutes.call(this);
+ }
+ }
```

### 4. Remove `discoverEmberDataModels` env variable

The environment variable `discoverEmberDataModels` is no longer used. If you wish to
not have `ember-cli-mirage` auto discover the models, just remove the `discoverEmberDataModels(config.store)`.

You should remove `discoverEmberDataModels` from `config/environment.js` file if it was set to `ENV['ember-cli-mirage']` before.

### 5. Remove `trackRequests` env variable

The environment variable `trackRequests` is no longer used.
If you want enabled [Pretender's `trackRequests` feature](https://github.com/pretenderjs/pretender#tracking-requests), this can be set in the `mirage/config.js` options:

```js
export default function(config) {
let finalConfig = {
...config,
trackRequests: true,
models: {
...discoverEmberDataModels(config.store),
...config.models
},
routes,
};

return createServer(finalConfig);
}
```

You should remove `trackRequests` from `config/environment.js` file if it was set to `ENV['ember-cli-mirage']` before.

## 2.0 Upgrade guide

There were a few breaking changes made in the 1.0 release.
The only breaking change made in the 2.0 release is dropped support for Node.js

### 1. Update import paths for miragejs imports

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -60,16 +60,21 @@ Asserting against models is basically another way to verify Mirage's database da

You can also assert against the actual HTTP requests and responses that are made during your test.

To do this, first enable [Pretender's `trackedRequests` feature](https://github.com/pretenderjs/pretender#tracking-requests) by enabling the `trackRequests` environment option:
To do this, first enable [Pretender's `trackedRequests` feature](https://github.com/pretenderjs/pretender#tracking-requests) by enabling the `trackRequests` option:

```js
// config/environment.js
module.exports = function(environment) {
if (environment === 'test') {
ENV['ember-cli-mirage'] = {
trackRequests: true
};
}
// mirage/config.js
export default function(config) {
let finalConfig = {
...config,
trackRequests: true,
models: {
...config.models
},
routes,
};

return createServer(finalConfig);
}
```

Expand All @@ -95,7 +100,7 @@ test("I can filter the table", async function(assert) {
});
```

In general we recommend asserting against Mirage's database and your UI, as the specifics of your app's HTTP requests should be considered implementation details of the behavior you're actually interested in verifying. But there's certainly valid reasons to drop down and assert against HTTP data.
In general, we recommend asserting against Mirage's database and your UI, as the specifics of your app's HTTP requests should be considered implementation details of the behavior you're actually interested in verifying. But there's certainly valid reasons to drop down and assert against HTTP data.



Expand Down