update(testing): upd. controller section (emberjs/ember.js#15933)

This updates the controller testing section according to the new Ember
Qunit testing patterns proposed in RFC#232.

Author: jayjayjpg

source/testing/testing-controllers.md

@@ -1,8 +1,9 @@
 _Unit testing methods and computed properties follows previous patterns shown
 in [Unit Testing Basics] because Ember.Controller extends Ember.Object._
 
-Unit testing controllers is very simple using the unit test helper which is part
-of the ember-qunit framework.
+Controllers can be tested using the `setupTest` helper which is part
+of the ember-qunit framework. The tests written for instances like `Ember.Controller` are
+also described as container tests.
 
 ### Testing Controller Actions
 
@@ -33,43 +34,49 @@ export default Controller.extend({
 ```
 
 The `setProps` action directly sets one property, and calls the method to set the other.
-In our generated test, ember-cli already uses the `moduleFor` helper to set up a test
+In our generated test file, ember-cli already uses the `module` and the `setupTest` helpers to set up a test
 container:
 
 ```tests/unit/controllers/posts-test.js
-import { moduleFor, test } from 'ember-qunit';
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
 
-moduleFor('controller:posts', {});
+module('Unit | Controller | posts', function(hooks) {
+  setupTest(hooks);
+});
 ```
 
-Next we use `this.subject()` to get an instance of the `PostsController` and
-write a test to check the action. `this.subject()` is a helper method from the
-`ember-qunit` library that returns a singleton instance of the module set up
-using `moduleFor`.
+Next we use the owner API to gain access to the controller we'd like to test.
+Using the `this.owner.lookup` method we get the instance of the `PostsController` and can check the action in our test.
+The `this.owner.lookup` helper returns objects generated by the framework in your applications
+and is also exposed in tests for your usage. Here it will return a singleton instance of the `PostsController`.
 
 ```tests/unit/controllers/posts-test.js
-import { moduleFor, test } from 'ember-qunit';
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
 
-moduleFor('controller:posts', {});
+module('Unit | Controller | posts', function(hooks) {
+  setupTest(hooks);
 
-test('should update A and B on setProps action', function(assert) {
-  assert.expect(4);
+  test('should update A and B on setProps action', function(assert) {
+    assert.expect(4);
 
-  // get the controller instance
-  const ctrl = this.subject();
+    // get the controller instance
+    let controller = this.owner.lookup('controller:posts');
 
-  // check the properties before the action is triggered
-  assert.equal(ctrl.get('propA'), 'You need to write tests', 'propA initialized');
-  assert.equal(ctrl.get('propB'), 'And write one for me too', 'propB initialized');
+    // check the properties before the action is triggered
+    assert.equal(controller.get('propA'), 'You need to write tests', 'propA initialized');
+    assert.equal(controller.get('propB'), 'And write one for me too', 'propB initialized');
 
-  // trigger the action on the controller by using the `send` method,
-  // passing in any params that our action may be expecting
-  ctrl.send('setProps', 'Testing Rocks!');
+    // trigger the action on the controller by using the `send` method,
+    // passing in any params that our action may be expecting
+    controller.send('setProps', 'Testing Rocks!');
 
-  // finally we assert that our values have been updated
-  // by triggering our action.
-  assert.equal(ctrl.get('propA'), 'Testing is cool', 'propA updated');
-  assert.equal(ctrl.get('propB'), 'Testing Rocks!', 'propB updated');
+    // finally we assert that our values have been updated
+    // by triggering our action.
+    assert.equal(controller.get('propA'), 'Testing is cool', 'propA updated');
+    assert.equal(controller.get('propB'), 'Testing Rocks!', 'propB updated');
+  });
 });
 ```
 
@@ -101,52 +108,40 @@ export default Controller.extend({
 });
 ```
 
-This time when we setup our `moduleFor` we need to pass an options object as
-our third argument that has the controller's `needs`.
-
-```tests/unit/controllers/comments-test.js
-import { moduleFor, test } from 'ember-qunit';
-import EmberObject from '@ember/object';
-import { run } from '@ember/runloop';
-
-moduleFor('controller:comments', 'Comments Controller', {
-  needs: ['controller:post']
-});
-```
-
 Now let's write a test that sets a property on our `post` model in the
 `PostController` that would be available on the `CommentsController`.
 
 ```tests/unit/controllers/comments-test.js
-import { moduleFor, test } from 'ember-qunit';
-import EmberObject from '@ember/object';
+import { module, test } from 'qunit';
+import { setupTest } from 'ember-qunit';
+import EmberObject from "@ember/object";
 import { run } from '@ember/runloop';
 
-moduleFor('controller:comments', 'Comments Controller', {
-  needs: ['controller:post']
-});
+module('Unit | Controller | comments', function(hooks) {
+  setupTest(hooks);
 
-test('should modify the post model', function(assert) {
-  assert.expect(2);
+  test('should modify the post model', function(assert) {
+    assert.expect(2);
 
-  // grab an instance of `CommentsController` and `PostController`
-  const ctrl = this.subject();
-  const postCtrl = ctrl.get('post');
+    // grab an instance of `CommentsController` and `PostController`
+    let controller = this.owner.lookup('controller:comments');
+    let postCtrl = controller.get('post');
 
-  // wrap the test in the run loop because we are dealing with async functions
-  run(function() {
+    // wrap the test in the run loop because we are dealing with async functions
+    run(function() {
 
-    // set a generic model on the post controller
-    postCtrl.set('model', Ember.Object.create({ title: 'foo' }));
+      // set a generic model on the post controller
+      postCtrl.set('model', Ember.Object.create({ title: 'foo' }));
 
-    // check the values before we modify the post
-    assert.equal(ctrl.get('title'), 'foo', 'title is set');
+      // check the values before we modify the post
+      assert.equal(controller.get('title'), 'foo', 'title is set');
 
-    // modify the title of the post
-    postCtrl.get('model').set('title', 'bar');
+      // modify the title of the post
+      postCtrl.get('model').set('title', 'bar');
 
-    // assert that the controllers title has changed
-    assert.equal(ctrl.get('title'), 'bar', 'title is updated');
+      // assert that the controllers title has changed
+      assert.equal(controller.get('title'), 'bar', 'title is updated');
+    });
   });
 });
 ```