Add Migration Guide

README.md

@@ -29,6 +29,11 @@ addon names and are expecting `ember-cli-qunit` instead. If you have issues
 with this then `ember install ember-cli-qunit`, which should work exactly
 the same.
 
+Upgrading
+------------------------------------------------------------------------------
+
+For instructions how to upgrade your test suite to the latest testing APIs, 
+please read our [Migration Guide](docs/migration.md).
 
 Usage
 ------------------------------------------------------------------------------
@@ -139,9 +144,9 @@ import { visit, currentURL } from '@ember/test-helpers';
 module('basic acceptance test', function(hooks) {
   setupApplicationTest(hooks);
 
-  test('can visit /', async function() {
+  test('can visit /', async function(assert) {
     await visit('/');
-    expect(currentURL()).to.equal('/');
+    assert.equal(currentURL(), '/');
   });
 });
 ```

docs/migration.md

@@ -0,0 +1,181 @@
+
+Migration Guide
+==============================================================================
+
+This guide provides instruction for upgrading your test suite from the 
+[Legacy APIs](legacy.md) to Ember's latest testing APIs based on 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).
+
+Upgrading to the new testing APIs
+------------------------------------------------------------------------------
+
+For the complete introduction to the new testing APIs, please read the
+latest [Ember Guides](https://guides.emberjs.com/v3.0.0/testing/). The
+following examples will give you an overview how to migrate your existing Ember
+QUnit based test suite.
+
+### Unit tests
+
+Before:
+
+```javascript
+import { test, moduleFor } from 'ember-qunit';
+
+moduleFor('controller:posts', {
+  // Specify the other units that are required for this test.
+  // needs: ['controller:foo']
+});
+
+// Replace this with your real tests.
+test('exists', function(assert) {
+  let controller = this.subject();
+  assert.ok(controller);
+});
+```
+
+After:
+
+```javascript
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
+
+module('SidebarController', function(hooks) {
+  setupTest(hooks);
+
+  // Replace this with your real tests.
+  test('exists', function() {
+    let controller = this.owner.lookup('controller:sidebar');
+    assert.ok(controller);
+  });
+});
+```
+
+#### Migration steps
+
+* Use `module` and `test` imported from `qunit` directly
+* Use `setupTest()` instead of `moduleFor()`
+* Use the Owner object given by `this.owner` directly instead of `this.subject()`
+
+You can use the
+[ember-qunit-codemod](https://github.com/rwjblue/ember-qunit-codemod)
+to update your test code automatically.
+
+### Component tests
+
+Before:
+
+```javascript
+import { test, moduleForComponent } from 'ember-qunit';
+import hbs from 'htmlbars-inline-precompile';
+
+moduleForComponent('GravatarImageComponent', {
+  integration: true
+});
+
+test('it renders', function(assert) {
+  this.render(hbs`{{gravatar-image}}`);
+  assert.equal(this.$('img').length, 1);
+});
+```
+
+After:
+
+```javascript
+import { module, test } from 'qunit';
+import { setupRenderingTest } from 'ember-qunit';
+import { render } from '@ember/test-helpers';
+import hbs from 'htmlbars-inline-precompile';
+
+module('GravatarImageComponent', function(hooks) {
+  setupRenderingTest(hooks);
+
+  test('renders', async function() {
+    await render(hbs`{{gravatar-image}}`);
+    assert.ok(this.element.querySelector('img'));
+  });
+});
+```
+
+#### Migration steps
+
+* Use `module` and `test` imported from `qunit` directly
+* Use `setupRenderingTest()` instead of `moduleForComponent()`
+* Render using the `render()` helper from `@ember/test-helpers` instead of
+  `this.render()`
+* `render()` is now always an async call, so use `async`/`await` to wait for it
+  to complete
+* Use `this.element` to get access to the rendered DOM
+* Do not use jQuery for DOM interaction, instead use the
+  [DOM Interaction Helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#dom-interaction-helpers)
+  from `@ember/test-helpers`
+
+You can use the
+[ember-qunit-codemod](https://github.com/rwjblue/ember-qunit-codemod)
+to update your test setup code automatically.
+
+For migrating to the DOM interaction helpers, you can use the
+[ember-test-helpers-codemod](https://github.com/simonihmig/ember-test-helpers-codemod)
+to automatically convert all or most of it.
+
+### Acceptance tests
+
+Before:
+
+```javascript
+
+import { test } from 'qunit';
+import moduleForAcceptance from 'app/tests/helpers/module-for-acceptance';
+
+moduleForAcceptance('basic acceptance test');
+
+test('can visit /', function() {
+  visit('/');
+
+  andThen(() => {
+    assert.equal(currentURL(), '/');
+  });
+});
+```
+
+After:
+
+
+```javascript
+import { module, test } from 'qunit';
+import { setupApplicationTest } from 'ember-qunit';
+import { visit, currentURL } from '@ember/test-helpers';
+
+module('basic acceptance test', function(hooks) {
+  setupApplicationTest(hooks);
+
+  test('can visit /', async function(assert) {
+    await visit('/');
+    assert.equal(currentURL(), '/');
+  });
+});
+```
+
+#### Migration steps
+
+* Use `module` and `test` imported from `qunit` directly
+* Use `setupApplicationTest()` instead of `moduleForAcceptance()` or `beforeEach`/`afterEach` hooks for setting up the
+  application
+* Use the [Routing Helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#routing-helpers)
+  from `@ember/test-helpers` instead of the global helpers, e.g. `visit`
+* Do not use the "global" test helpers for DOM interaction, instead use the
+  [DOM Interaction Helpers](https://github.com/emberjs/ember-test-helpers/blob/master/API.md#dom-interaction-helpers)
+  from `@ember/test-helpers`
+* use `async`/`await` to wait for asynchronous operations like `visit()` or
+  `click()`
+* use `this.element` to get access to the rendered DOM
+
+You can use the
+[ember-qunit-codemod](https://github.com/rwjblue/ember-qunit-codemod)
+to update your test setup code automatically.
+
+For migrating from the global test helpers to those proved by
+`@ember/test-helpers`, you can use the
+[ember-test-helpers-codemod](https://github.com/simonihmig/ember-test-helpers-codemod)
+to assist you with that task.