docs(testing): feedback from Joe Eames/add more scenarios (#2391)

Author: wardbell

public/docs/_examples/testing/ts/app-specs.html

@@ -42,7 +42,7 @@
       'app/model/hero.spec',
       'app/model/http-hero.service.spec',
       'app/shared/title-case.pipe.spec',
-      'app/twain.component.spec',
+      'app/shared/twain.component.spec',
       'app/welcome.component.spec'
     ];
   </script>

public/docs/_examples/testing/ts/app/app.component.spec.ts

@@ -8,7 +8,7 @@ import { AppComponent }    from './app.component';
 import { BannerComponent } from './banner.component';
 import { SharedModule }    from './shared/shared.module';
 
-import { Router, FakeRouter, FakeRouterLinkDirective, FakeRouterOutletComponent
+import { Router, RouterStub, RouterLinkDirectiveStub, RouterOutletStubComponent
 } from '../testing';
 
 
@@ -20,9 +20,9 @@ describe('AppComponent & TestModule', () => {
     TestBed.configureTestingModule({
       declarations: [
         AppComponent, BannerComponent,
-        FakeRouterLinkDirective, FakeRouterOutletComponent
+        RouterLinkDirectiveStub, RouterOutletStubComponent
       ],
-      providers: [{ provide: Router, useClass: FakeRouter }],
+      providers: [{ provide: Router, useClass: RouterStub }],
       schemas:   [NO_ERRORS_SCHEMA]
     })
 
@@ -49,9 +49,9 @@ function tests() {
 
     const links = fixture.debugElement
       // find all elements with an attached FakeRouterLink directive
-      .queryAll(By.directive(FakeRouterLinkDirective))
+      .queryAll(By.directive(RouterLinkDirectiveStub))
       // use injector to get the RouterLink directive instance attached to each element
-      .map(de => de.injector.get(FakeRouterLinkDirective) as FakeRouterLinkDirective);
+      .map(de => de.injector.get(RouterLinkDirectiveStub) as RouterLinkDirectiveStub);
 
     expect(links.length).toBe(3, 'should have 3 links');
     expect(links[0].linkParams).toBe('/dashboard', '1st link should go to Dashboard');
@@ -63,11 +63,11 @@ function tests() {
 
     // Heroes RouterLink DebugElement
     const heroesLinkDe = fixture.debugElement
-      .queryAll(By.directive(FakeRouterLinkDirective))[1];
+      .queryAll(By.directive(RouterLinkDirectiveStub))[1];
 
     expect(heroesLinkDe).toBeDefined('should have a 2nd RouterLink');
 
-    const link = heroesLinkDe.injector.get(FakeRouterLinkDirective) as FakeRouterLinkDirective;
+    const link = heroesLinkDe.injector.get(RouterLinkDirectiveStub) as RouterLinkDirectiveStub;
 
     expect(link.navigatedTo).toBeNull('link should not have navigate yet');
 
@@ -101,8 +101,8 @@ describe('AppComponent & AppModule', () => {
     // Separate override because cannot both `set` and `add/remove` in same override
     .overrideModule(AppModule, {
       add: {
-        declarations: [ FakeRouterLinkDirective, FakeRouterOutletComponent ],
-        providers:    [{ provide: Router, useClass: FakeRouter }]
+        declarations: [ RouterLinkDirectiveStub, RouterOutletStubComponent ],
+        providers:    [{ provide: Router, useClass: RouterStub }]
       }
     })
 

public/docs/_examples/testing/ts/app/dashboard/dashboard.component.spec.ts

@@ -12,11 +12,11 @@ import { Router } from '@angular/router';
 import { DashboardComponent } from './dashboard.component';
 import { DashboardModule }    from './dashboard.module';
 
-// #docregion fake-router
-class FakeRouter {
+// #docregion router-stub
+class RouterStub {
   navigateByUrl(url: string) { return url;  }
 }
-// #enddocregion fake-router
+// #enddocregion router-stub
 
 beforeEach ( addMatchers );
 
@@ -73,7 +73,7 @@ function compileAndCreate() {
     TestBed.configureTestingModule({
       providers: [
         { provide: HeroService, useClass: FakeHeroService },
-        { provide: Router,      useClass: FakeRouter }
+        { provide: Router,      useClass: RouterStub }
       ]
     })
     .compileComponents().then(() => {

public/docs/_examples/testing/ts/app/hero/hero-detail.component.html

@@ -1,10 +1,11 @@
+<!-- #docregion -->
 <div *ngIf="hero">
   <h2><span>{{hero.name | titlecase}}</span> Details</h2>
   <div>
     <label>id: </label>{{hero.id}}</div>
   <div>
-    <label>name: </label>
-    <input [(ngModel)]="hero.name" placeholder="name" />
+    <label for="name">name: </label>
+    <input id="name" [(ngModel)]="hero.name" placeholder="name" />
   </div>
   <button (click)="save()">Save</button>
   <button (click)="cancel()">Cancel</button>

public/docs/_examples/testing/ts/app/hero/hero-detail.component.no-testbed.spec.ts

@@ -1,20 +1,20 @@
 import { HeroDetailComponent } from './hero-detail.component';
 import { Hero }                from '../model';
 
-import { FakeActivatedRoute }  from '../../testing';
+import { ActivatedRouteStub }  from '../../testing';
 
 //////////  Tests  ////////////////////
 
 describe('HeroDetailComponent - no TestBed', () => {
-  let activatedRoute: FakeActivatedRoute;
+  let activatedRoute: ActivatedRouteStub;
   let comp: HeroDetailComponent;
   let expectedHero: Hero;
   let hds: any;
   let router: any;
 
   beforeEach( done => {
     expectedHero = new Hero(42, 'Bubba');
-    activatedRoute = new FakeActivatedRoute();
+    activatedRoute = new ActivatedRouteStub();
     activatedRoute.testParams = { id: expectedHero.id };
 
     router = jasmine.createSpyObj('router', ['navigate']);

public/docs/_examples/testing/ts/app/hero/hero-detail.component.spec.ts

@@ -1,3 +1,4 @@
+// #docplaster
 import {
   async, ComponentFixture, fakeAsync, inject, TestBed, tick
 } from '@angular/core/testing';
@@ -7,7 +8,7 @@ import { DebugElement } from '@angular/core';
 
 import {
   addMatchers, newEvent,
-  ActivatedRoute, FakeActivatedRoute, Router, FakeRouter
+  ActivatedRoute, ActivatedRouteStub, Router, RouterStub
 } from '../../testing';
 
 import { HEROES, FakeHeroService } from '../model/testing';
@@ -18,7 +19,7 @@ import { HeroDetailService }   from './hero-detail.service';
 import { Hero, HeroService }   from '../model';
 
 ////// Testing Vars //////
-let activatedRoute: FakeActivatedRoute;
+let activatedRoute: ActivatedRouteStub;
 let comp: HeroDetailComponent;
 let fixture: ComponentFixture<HeroDetailComponent>;
 let page: Page;
@@ -29,7 +30,7 @@ describe('HeroDetailComponent', () => {
 
   beforeEach( async(() => {
     addMatchers();
-    activatedRoute = new FakeActivatedRoute();
+    activatedRoute = new ActivatedRouteStub();
 
     TestBed.configureTestingModule({
       imports: [ HeroModule ],
@@ -40,12 +41,13 @@ describe('HeroDetailComponent', () => {
       providers: [
         { provide: ActivatedRoute, useValue: activatedRoute },
         { provide: HeroService,    useClass: FakeHeroService },
-        { provide: Router,         useClass: FakeRouter},
+        { provide: Router,         useClass: RouterStub},
       ]
     })
     .compileComponents();
   }));
 
+  // #docregion route-good-id
   describe('when navigate to hero id=' + HEROES[0].id, () => {
     let expectedHero: Hero;
 
@@ -55,51 +57,53 @@ describe('HeroDetailComponent', () => {
       createComponent();
     }));
 
+  // #docregion selected-tests
     it('should display that hero\'s name', () => {
       expect(page.nameDisplay.textContent).toBe(expectedHero.name);
     });
+  // #enddocregion route-good-id
 
     it('should navigate when click cancel', () => {
       page.cancelBtn.triggerEventHandler('click', null);
       expect(page.navSpy.calls.any()).toBe(true, 'router.navigate called');
     });
 
-    it('should save when click save', () => {
+    it('should save when click save but not navigate immediately', () => {
       page.saveBtn.triggerEventHandler('click', null);
       expect(page.saveSpy.calls.any()).toBe(true, 'HeroDetailService.save called');
+      expect(page.navSpy.calls.any()).toBe(false, 'router.navigate not called');
     });
 
-    it('should navigate when click click save resolves', fakeAsync(() => {
+    it('should navigate when click save and save resolves', fakeAsync(() => {
       page.saveBtn.triggerEventHandler('click', null);
-      tick(); // waits for async save to "complete" before navigating
+      tick(); // wait for async save to "complete" before navigating
       expect(page.navSpy.calls.any()).toBe(true, 'router.navigate called');
     }));
 
-
     // #docregion title-case-pipe
-    it('should convert original hero name to Title Case', () => {
-      expect(page.nameDisplay.textContent).toBe(comp.hero.name);
-    });
-    // #enddocregion title-case-pipe
-
     it('should convert hero name to Title Case', fakeAsync(() => {
       const inputName = 'quick BROWN  fox';
-      const expectedName = 'Quick Brown  Fox';
+      const titleCaseName = 'Quick Brown  Fox';
 
-      // simulate user entering new name in input
+      // simulate user entering new name into the input box
       page.nameInput.value = inputName;
 
       // dispatch a DOM event so that Angular learns of input value change.
-      // detectChanges() makes ngModel push input value to component property
-      // and Angular updates the output span
       page.nameInput.dispatchEvent(newEvent('input'));
+
+      // detectChanges() makes [(ngModel)] push input value to component property
+      // and Angular updates the output span through the title pipe
       fixture.detectChanges();
-      expect(page.nameDisplay.textContent).toBe(expectedName, 'hero name display');
-      expect(comp.hero.name).toBe(inputName, 'comp.hero.name');
-    }));
 
+      expect(page.nameDisplay.textContent).toBe(titleCaseName);
+    }));
+    // #enddocregion title-case-pipe
+  // #enddocregion selected-tests
+  // #docregion route-good-id
   });
+  // #enddocregion route-good-id
 
+  // #docregion route-no-id
   describe('when navigate with no hero id', () => {
     beforeEach( async( createComponent ));
 
@@ -111,7 +115,9 @@ describe('HeroDetailComponent', () => {
       expect(page.nameDisplay.textContent).toBe('');
     });
   });
+  // #enddocregion route-no-id
 
+  // #docregion route-bad-id
   describe('when navigate to non-existant hero id', () => {
     beforeEach( async(() => {
       activatedRoute.testParams = { id: 99999 };
@@ -123,6 +129,7 @@ describe('HeroDetailComponent', () => {
       expect(page.navSpy.calls.any()).toBe(true, 'router.navigate called');
     });
   });
+  // #enddocregion route-bad-id
 
   ///////////////////////////
 
@@ -145,22 +152,24 @@ describe('HeroDetailComponent', () => {
 
 /////////// Helpers /////
 
+// #docregion create-component
 /** Create the HeroDetailComponent, initialize it, set test variables  */
 function createComponent() {
   fixture = TestBed.createComponent(HeroDetailComponent);
   comp    = fixture.componentInstance;
   page    = new Page();
 
-  // change detection triggers ngOnInit which gets a hero
+  // 1st change detection triggers ngOnInit which gets a hero
   fixture.detectChanges();
   return fixture.whenStable().then(() => {
-    // got the hero and updated component
-    // change detection updates the view
+    // 2nd change detection displays the async-fetched hero
     fixture.detectChanges();
     page.addPageElements();
   });
 }
+// #enddocregion create-component
 
+// #docregion page
 class Page {
   gotoSpy:      jasmine.Spy;
   navSpy:       jasmine.Spy;
@@ -173,24 +182,24 @@ class Page {
 
   constructor() {
     // Use component's injector to see the services it injected.
-    let compInjector = fixture.debugElement.injector;
-    let hds          = compInjector.get(HeroDetailService);
-    let router       = compInjector.get(Router);
-    this.gotoSpy     = spyOn(comp, 'gotoList').and.callThrough();
-    this.saveSpy     = spyOn(hds, 'saveHero').and.callThrough();
-    this.navSpy      = spyOn(router, 'navigate').and.callThrough();
+    const compInjector = fixture.debugElement.injector;
+    const hds          = compInjector.get(HeroDetailService);
+    const router       = compInjector.get(Router);
+    this.gotoSpy       = spyOn(comp, 'gotoList').and.callThrough();
+    this.saveSpy       = spyOn(hds, 'saveHero').and.callThrough();
+    this.navSpy        = spyOn(router, 'navigate').and.callThrough();
   }
 
-  /** Add page elements after page initializes  */
+  /** Add page elements after hero arrives */
   addPageElements() {
     if (comp.hero) {
-      // have a hero so these DOM elements can be reached
-      let buttons = fixture.debugElement.queryAll(By.css('button'));
+      // have a hero so these elements are now in the DOM
+      const buttons    = fixture.debugElement.queryAll(By.css('button'));
       this.saveBtn     = buttons[0];
       this.cancelBtn   = buttons[1];
       this.nameDisplay = fixture.debugElement.query(By.css('span')).nativeElement;
       this.nameInput   = fixture.debugElement.query(By.css('input')).nativeElement;
     }
   }
 }
-
+// #enddocregion page

public/docs/_examples/testing/ts/app/hero/hero-detail.component.ts

@@ -1,5 +1,6 @@
 import { Component, Input, OnInit } from '@angular/core';
 import { ActivatedRoute, Router }   from '@angular/router';
+import 'rxjs/add/operator/pluck';
 
 import { Hero }              from '../model';
 import { HeroDetailService } from './hero-detail.service';
@@ -16,31 +17,34 @@ import { HeroDetailService } from './hero-detail.service';
 export class HeroDetailComponent implements OnInit {
   @Input() hero: Hero;
 
+  // #docregion ctor
   constructor(
     private heroDetailService: HeroDetailService,
     private route: ActivatedRoute,
     private router: Router) {
   }
-
-  ngOnInit() {
-    let id = this.route.snapshot.params['id'];
-
-    // tslint:disable-next-line:triple-equals
-    if (id == undefined) {
-      // no id; act as if is new
-      this.hero = new Hero();
-    } else {
-      this.heroDetailService.getHero(id).then(hero => {
-        if (hero) {
-          this.hero = hero;
-        } else {
-          this.gotoList(); // id not found; navigate to list
-        }
-      });
-    }
+  // #enddocregion ctor
+
+  // #docregion ng-on-init
+  ngOnInit(): void {
+    // get hero when `id` param changes
+    this.route.params.pluck<string>('id')
+      .forEach(id => this.getHero(id))
+      .catch(() => this.hero = new Hero()); // no id; should edit new hero
+  }
+  // #enddocregion ng-on-init
+
+  private getHero(id: string): void {
+    this.heroDetailService.getHero(id).then(hero => {
+      if (hero) {
+        this.hero = hero;
+      } else {
+        this.gotoList(); // id not found; navigate to list
+      }
+    });
   }
 
-  save() {
+  save(): void {
     this.heroDetailService.saveHero(this.hero).then(() => this.gotoList());
   }