Enhance API for testing Inputs and Outputs (#30)

Author: hmil

docs/docs/api-reference.md

@@ -39,7 +39,7 @@ const dependencyService = getMock(MyServiceDependency);
 when(dependencyService.greet('John')).return('Hello John').once();
 ```
 
-### `renderComponent<T>(component: Type<T>, module: Type<any> | ModuleWithProviders<any>): Promise<Rendering<T, never>>`
+### `renderComponent<T, TBindings>(component: Type<T>, module: Type<any> | ModuleWithProviders<any>, options: RenderSettings<TBindings>): Promise<Rendering<T, never>>`
 
 Shallow-renders a component, meaning that its children components are not rendered themselves, and any constructor dependency is mocked.
 

docs/docs/best-practices.md

@@ -100,9 +100,9 @@ describe('SomeComponent', () => {
 
     let rendering: Rendering<SomeComponent, unknown>;
 
-    beforeEach(async () => {
-        rendering = await renderComponent(SomeComponent, AppModule);
-    });
+    beforeEach(fakeAsync(() => {
+        rendering = renderComponent(SomeComponent, AppModule);
+    }));
 
     it('can click a button', () => {
         // Bad: This test is not readable
@@ -117,9 +117,9 @@ describe('SomeComponent', () => {
 
     let page: Page;
 
-    beforeEach(async () => {
-        page = new Page(await renderComponent(SomeComponent, AppModule));
-    });
+    beforeEach(fakeAsync(() => {
+        page = new Page(renderComponent(SomeComponent, AppModule));
+    }));
 
     it('can click a button', () => {
         // Bad: This test is not readable

docs/docs/component-bindings.md

@@ -1,12 +1,123 @@
 ---
 id: component-bindings
-title: Testing Component Bindings
-sidebar_label: Testing Component Bindings
+title: Testing @Input and @Ouput
+sidebar_label: '@Input and @Output'
 ---
 
-TODO: Write proper documentation.
-- Use `getShallow` instead of `renderComponent` and bind values
-- Use page object `setBoundValues` in a fakeAsync context.
+In the previous section, we have seen how to mock services and child components in a component test.  
+In this section we will cover how to inject data into the inputs of our components, and how to assert events emitted on its outputs.
 
+# Binding input data
+
+Consider the component below:
+
+```ts
+@Component({
+    selector: 'greetings-component',
+    templateUrl: `
+        <span test-id="message">Hello {{name}}</span>
+    `
+})
+export class GreetingsComponent {
+    @Input()
+    userName: string;
+}
+```
+
+We would like to verify that the label gets updated with the user name.
+
+As always, we create a page object to model the interactions with our component:
+
+```ts
+class Page<T> extends BasePage<GreetingsComponent, T> {
+
+    get messageText(): string {
+        return (this.rendering.find('[test-id=message]').nativeElement as HTMLElement).innerText
+    }
+}
+```
+
+Then, we use `setInputs` on the page object to update the input bindings and trigger a change detection cycle:
+
+```ts
+it('greets the user', fakeAsync(() => {
+    // Render the component with initial input values
+    const page = new Page(renderComponent(GreetingsComponent, GreetingsModule, {
+        inputs: {
+            userName: 'John'
+        }
+    }));
+    expect(page.messageText).toBe('Hello John');
+
+    // Set input values and test again
+    page.setInputs({
+        userName: 'Atul'
+    });
+    expect(page.messageText).toBe('Hello Atul');
+}));
+```
+
+Setting input values after the component has been initialized can be useful when you want to test `onChanges` logic.
+
+:::caution
+
+You can only use `setInputs` for inputs that you have initialized in `renderComponent`. This is what the template type parameter `T` in `Page<T>` is for.
+
+:::
+
+# Test output events
+
+Let's consider a keypad component which lets users type in a numeric code:
+
+```ts
+@Component({
+    selector: 'keypad-component',
+    templateUrl: `
+        <button *ngFor="number of numbers" [test-id]="number" (click)="onClick(number)></button>
+    `
+})
+export class KeypadComponent {
+
+    numbers = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+    code = '';
+
+    @Output()
+    codeChange = new EventEmitter<string>();
+
+    onClick(n: number) {
+        this.code += String(n);
+        this.codeChange.emit(this.code);
+    }
+}
+```
+
+We would like to test the emitted output.
+
+
+```ts
+class Page<T> extends BasePage<KeypadComponent, T> {
+
+    getButton(n: number): HTMLButtonElement {
+        return this.rendering.find(`[test-id=${n}]`).nativeElement;
+    }
+}
+```
+
+The page object exposes outputs utilities on `page.outputs`. Use `capture()` to create an array which receives all future events emitted on this output:
+
+```ts
+it('lets the user type a combination', fakeAsync(() => {
+    const page = new Page(renderComponent(KeypadComponent, KeypadModule));
+
+    const emittedEvents = page.outputs.codeChage.capture();
+
+    page.getButton(1).click();
+    page.getButton(3).click();
+    page.getButton(3).click();
+    page.getButton(7).click();
+
+    expect(emittedEvents).toEqual(['1', '13', '133', '1337'])
+}));
+```
 
-See example in [fancy-button.component.spec.ts](https://github.com/hmil/ng-vacuum/blob/080e8803df257338497dd7b07f663ce502b03aac/test/ng7/src/app/fancy-button.component.spec.ts)

docs/docs/component-test.md

@@ -51,7 +51,7 @@ export class MyComponent {
 }
 ```
 
-The sample component uses the global `console` object, injected using an [`InjectionToken`](https://angular.io/api/core/InjectionToken), to give this tutorial a bit more uumpf.
+The sample component uses the global `console` object, injected using an [`InjectionToken`](https://angular.io/api/core/InjectionToken), to give this tutorial a bit more depth.
 
 
 ## Scaffolding
@@ -62,14 +62,15 @@ NgVcuum provides a utility class to simplify the setup of the page object
 
 ```ts
 import { BasePage, renderComponent } from 'ng-vacuum';
+import { fakeAsync } from '@angular/core/testing';
 
 describe('MyComponent', () => {
 
     let page: Page;
 
-    beforeEach(async () => {
-        page = new Page(await renderComponent(MyComponent, AppModule));
-    });
+    beforeEach(fakeAsync(() => {
+        page = new Page(renderComponent(MyComponent, AppModule));
+    }));
 });
 
 class Page extends BasePage<MyComponent> { }
@@ -137,10 +138,10 @@ We need to specify the behavior of `AuthService` _before_ rendering the componen
 Let's do this. We move the mock behavior to the `beforeEach` function:
 
 ```ts
-beforeEach(async () => {
+beforeEach(fakeAsync(() => {
     when(getMock(AuthService).authenticated).return(false); // Add here
-    page = new Page(await renderComponent(AppComponent, AppModule));
-});
+    page = new Page(renderComponent(AppComponent, AppModule));
+}));
 
 it('lets user log in when not authenticated', fakeAsync(() => {
     // Remove from here
@@ -182,11 +183,11 @@ describe('AppComponent', () => {
 
     let isAuthenticated: boolean;
 
-    beforeEach(async () => {
+    beforeEach(fakeAsync(() => {
         isAuthenticated = false;
         when(getMock(AuthService).isAuthenticated()).useGetter(() => isAuthenticated);
-        page = new Page(await renderComponent(AppComponent, AppModule));
-    });
+        page = new Page(renderComponent(AppComponent, AppModule));
+    }));
 
 // snip
 ```
@@ -225,12 +226,12 @@ describe('AppComponent', () => {
     let page: Page;
     let isAuthenticated: boolean;
 
-    beforeEach(async () => {
+    beforeEach(fakeAsync(() => {
         isAuthenticated = false;
         // Mock data required by the template
         when(getMock(AuthService).isAuthenticated()).useGetter(() => isAuthenticated);
-        page = new Page(await renderComponent(AppComponent, AppModule));
-    });
+        page = new Page(renderComponent(AppComponent, AppModule));
+    }));
 
     it('lets user log in when not authenticated', fakeAsync(() => {
         // Ensure the tempalte is fully rendered

docs/sidebars.js

@@ -1,7 +1,7 @@
 module.exports = {
   someSidebar: {
-    "Getting Started": ['setup', 'service-test', 'component-test', 'component-bindings'],
-    "Guides": ['mocking-techniques', 'best-practices', 'injection-tokens', 'ng-model'],
+    "Getting Started": ['setup', 'service-test', 'component-test'],
+    "Guides": ['component-bindings', 'mocking-techniques', 'best-practices', 'injection-tokens', 'ng-model'],
     "Reference": ['api-reference'],
   },
 };