<NME> README.md
<BEF> 
ember-mocha
==============================================================================

[![Latest NPM release][npm-badge]][npm-badge-url]
[![TravisCI Build Status][travis-badge]][travis-badge-url]

[npm-badge]: https://img.shields.io/npm/v/ember-mocha.svg
[npm-badge-url]: https://www.npmjs.com/package/ember-mocha
[travis-badge]: https://img.shields.io/travis/emberjs/ember-mocha/master.svg
[travis-badge-url]: https://travis-ci.org/emberjs/ember-mocha

ember-mocha simplifies testing of Ember applications with
[Mocha](https://mochajs.org/) by providing Mocha-specific wrappers around the
helpers contained in
[ember-test-helpers](https://github.com/switchfly/ember-test-helpers).


Installation
------------------------------------------------------------------------------

- Ember.js v3.4 or above
- Ember CLI v2.13 or above
- Node.js 8 or above


Installation
------------------------------------------------------------------------------

`ember-mocha` is an [Ember CLI](http://www.ember-cli.com/) addon, so install it
as you would any other addon:

```sh
$ ember install ember-mocha
```

Some other addons are detecting the test framework based on the installed
addon names and are expecting `ember-cli-mocha` instead. If you have issues
with this then `ember install ember-cli-mocha`, which should work exactly
the same.


Usage
------------------------------------------------------------------------------

The following section describes the use of Ember Mocha with the latest modern
Ember testing APIs, as laid out in the RFCs
[232](https://github.com/emberjs/rfcs/blob/master/text/0232-simplify-qunit-testing-api.md)
and
[268](https://github.com/emberjs/rfcs/blob/master/text/0268-acceptance-testing-refactor.md).

For the older APIs have a look at our [Legacy Guide](docs/legacy.md).

### Setting the Application

Your `tests/test-helper.js` file should look similar to the following, to
correctly setup the application required by `@ember/test-helpers`:

```javascript
import Application from '../app';
import config from '../config/environment';
import { setApplication } from '@ember/test-helpers';
import { start } from 'ember-mocha';

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

Also make sure that you have set `ENV.APP.autoboot = false;` for the `test`
environment in your `config/environment.js`.

### Setup Tests

The `setupTest()` function can be used to setup a unit test for any kind
of "module/unit" of your application that can be looked up in a container.

It will setup your test context with:

* `this.owner` to interact with Ember's [Dependency Injection](https://guides.emberjs.com/v3.0.0/applications/dependency-injection/)
  system
* `this.set()`, `this.setProperties()`, `this.get()`, and `this.getProperties()`
* `this.pauseTest()` method to allow easy pausing/resuming of tests

For example, the following is a unit test for the `SidebarController`:

```javascript
import { expect } from 'chai';
import { describe, it } from 'mocha';
import { setupTest } from 'ember-mocha';

describe('SidebarController', function() {
  setupTest();

  // Replace this with your real tests.
  it('exists', function() {
    let controller = this.owner.lookup('controller:sidebar');
    expect(controller).to.be.ok;
  });
});
```

If you find that test helpers from other addons want you to pass a `hooks`
object you can do so like this:

```javascript
let hooks = setupTest();
setupMirage(hooks);
```

This will make sure that in functions passed to `hooks.afterEach()` the
`this.owner` and other things that `setupTest()` sets up are still available.
Mocha itself runs `afterEach` hooks in a different order than QUnit, which is
why this "workaround" is sometimes needed.


### Setup Rendering Tests

The `setupRenderingTest()` function is specifically designed for tests that
render arbitrary templates, including components and helpers.

It will setup your test context the same way as `setupTest()`, and additionally:

* Initializes Ember's renderer to be used with the
  [Rendering helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#rendering-helpers),
  specifically `render()`
* Adds `this.element` to your test context which returns the DOM element
  representing the wrapper around the elements that were rendered via
  `render()`
* sets up the [DOM Interaction Helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#dom-interaction-helpers)
  from `@ember/test-helpers` (`click()`, `fillIn()`, ...)

```javascript
import { expect } from 'chai';
import { describe, it } from 'mocha';
import { setupRenderingTest } from 'ember-mocha';
import { render } from '@ember/test-helpers';
```


Contributing
------------------------------------------------------------------------------

Copyright and License
------------------------------------------------------------------------------

Copyright 2014 Switchfly

This product includes software developed at
Switchfly (http://www.switchfly.com).

NOTICE: Only our own original work is licensed under the terms of the Apache
License Version 2.0. The licenses of some libraries might impose different
redistribution or general licensing terms than those stated in the Apache
License. Users and redistributors are hereby requested to verify these
conditions and agree upon them.

<MSG> README: Add "Upgrading" section

<DFF> @@ -15,6 +15,9 @@ ember-mocha simplifies unit testing of Ember applications with
 helpers contained in
 [ember-test-helpers](https://github.com/switchfly/ember-test-helpers).
 
+*Upgrading from an earlier version? Have a look at our
+[Upgrade Guide](#upgrading) below.*
+
 
 Installation
 ------------------------------------------------------------------------------
@@ -137,6 +140,75 @@ describe('Contact', function() {
 ```
 
 
+Upgrading
+------------------------------------------------------------------------------
+
+Previous releases promoted the use of `describeModule()`,
+`describeComponent()` and `describeModel()` instead of the `describe()`
+function of Mocha itself. These functions have been deprecated and replaced
+by the `setupTest()` functions mentioned [above](#setup-tests). The following
+example will explain how to update your code.
+
+Before:
+
+```js
+import {expect} from 'chai';
+import {it} from 'mocha';
+import {describeModule} from 'ember-mocha';
+
+describeModule(
+  'route:subscribers',
+  'Unit: Route: subscribers',
+  {
+    needs: ['service:notifications']
+  },
+  function() {
+    it('exists', function() {
+      let route = this.subject();
+      expect(route).to.be.ok;
+    });
+  }
+);
+```
+
+After:
+
+```js
+import {expect} from 'chai';
+import {it, describe} from 'mocha';
+import {setupTest} from 'ember-mocha';
+
+describe('Unit: Route: subscribers', function() {
+  setupTest('route:subscribers', {
+    needs: ['service:notifications']
+  });
+
+  it('exists', function() {
+    let route = this.subject();
+    expect(route).to.be.ok;
+  });
+});
+```
+
+- import `it` from `mocha` instead of `ember-mocha`
+- replace the `describeModule` import with a `setupTest` import
+- add a `setupTest()` call to the test `function` with the second and third
+  argument of the `describeModule()` call (module name and options)
+- replace the `describeModule()` call with a `describe()` call with the first
+  and fourth argument of the `describeModule()` call (description and test
+  function)
+
+Instead of refactoring all your files by hand we recommend to use the
+[ember-mocha-codemods](https://github.com/Turbo87/ember-mocha-codemods)
+to automatically convert your tests:
+
+```
+npm install -g jscodeshift
+jscodeshift -t https://raw.githubusercontent.com/Turbo87/ember-mocha-codemods/master/import-it-from-mocha.js tests
+jscodeshift -t https://raw.githubusercontent.com/Turbo87/ember-mocha-codemods/master/new-testing-api.js tests
+```
+
+
 Contributing
 ------------------------------------------------------------------------------
 

README: Add "Upgrading" section