ngx-speculoos 12.0.1 → 13.0.0

package/README.md

@@ -18,6 +18,7 @@ how to write Angular unit tests.
   - [Getting started](#getting-started)
 - [Features in details](#features-in-details)
   - [ComponentTester](#componenttester)
+  - [Automatic change detection](#automatic-change-detection)
   - [Queries](#queries)
     - [Queries for elements](#queries-for-elements)
     - [CSS and Type selectors](#css-and-type-selectors)
@@ -37,6 +38,7 @@ how to write Angular unit tests.
   - [Can I use the TestElement methods to act on the component element itself, rather than a sub-element?](#can-i-use-the-testelement-methods-to-act-on-the-component-element-itself-rather-than-a-sub-element)
 - [Issues, questions](#issues-questions)
 - [Complete example](#complete-example)
+- [Upgrading to v13](#upgrading-to-v13)
 
 ## Quick presentation
 
@@ -181,7 +183,7 @@ describe('My component', () => {
     });
     
     tester = new MyComponentTester();
-    tester.detectChanges();
+    tester.change();
   });
   
   it('should ...', () => {
@@ -189,6 +191,74 @@ describe('My component', () => {
   });
 ```
 
+### Automatic change detection
+
+The future of Angular is zoneless. Without ZoneJS, components have to make sure to properly notify
+Angular that they must be checked for changes, typically by updating signals.
+Instead of imperatively triggering change detections in tests, it's thus a better idea to let
+Angular decide if change detection must be run, in order to spot bugs where the component doesn't
+properly handle its state changes.
+
+This can be done by:
+
+- adding a provider in the testing module to configure the fixtures to be in _automatic_ mode
+- awaiting the component fixture stability when the test *thinks* that a change detection should
+  automatically happen.
+
+When the `provideAutomaticChangeDetection()` provider is added, the `ComponentTester` will run in
+_automatic_ mode. In this mode, calling `detectChanges()` throws an error, because you should always
+let Angular decide if change detection is necessary.
+
+Here's an example of a test that uses this technique:
+
+```ts
+class AppComponentTester extends ComponentTester<AppComponent> {
+  constructor() {
+    super(AppComponent);
+  }
+
+  get incrementButton() {
+    return this.button('button');
+  }
+
+  get count() {
+    return this.element('#count');
+  }
+}
+
+describe('AppComponent', () => {
+  let tester: AppComponentTester;
+
+  beforeEach(async () => {
+    TestBed.configureTestingModule({
+      providers: [
+        provideComponentFixtureAutoDetection(),
+        provideExperimentalZonelessChangeDetection() // if you already uses zoneless also add this provider
+      ]
+    });
+
+    jasmine.addMatchers(speculoosMatchers);
+    
+    tester = new AppComponentTester();
+    // a first call to change() is necessary to let Angular run its first change detection
+    await tester.change();
+  });
+
+  it('should display the counter value and increment it', async () => {
+    expect(tester.count).toHaveText('0');
+    
+    // this clicks the button and then lets Angular decide if a CD is necessary, and waits until
+    // the DOM has been updated (or not)
+    await tester.incrementButton.click();
+    
+    expect(tester.count).toHaveText('1');
+  });
+});
+```
+
+In _automatic_ mode, your test functions should be `async`, and each action you do with the elements
+(`click()`, `dispatchEvent`, etc.) should be awaited.
+
 ### Queries
 
 #### Queries for elements
@@ -281,12 +351,12 @@ class TestDatepicker extends TestHtmlElement<HTMLElement> {
     return this.input('input');
   }
 
-  setDate(year: number, month: number, day: number) {
-    this.inputField.fillWith(`${year}-${month}-${day}`);
+  async setDate(year: number, month: number, day: number) {
+    await this.inputField.fillWith(`${year}-${month}-${day}`);
   }
 
-  toggleDropdown() {
-    this.button('button').click();
+  async toggleDropdown() {
+    await this.button('button').click();
   }
 }
 ```
@@ -301,14 +371,26 @@ get birthDate() {
 ```
 
 ```typescript
-it('should not save if birth date is in the future') {
+it('should not save if birth date is in the future', () =>) {
   // ...
   tester.birthDate.setDate(2200, 1, 1);
   tester.save.click();
   expect(userService.create).not.toHaveBenCalled();
-}
+});
 ```
 
+or, in _automatic_ mode
+
+```typescript
+it('should not save if birth date is in the future'), async () => {
+  // ...
+  await tester.birthDate.setDate(2200, 1, 1);
+  await tester.save.click();
+  expect(userService.create).not.toHaveBenCalled();
+});
+```
+
+
 #### Subqueries
 
 A query is made from the root `ComponentTester`. But `TestElement` themselves also support queries.
@@ -540,10 +622,10 @@ using the usual queries.
 
 ## Gotchas
 
-### When do I need to call `detectChanges()`?
+### When do I need to call `change` or `detectChanges()`?
 
-Any event dispatched through a `TestElement` automatically calls `detectChanges()` for you.
-But you still need to call `detectChanges()` by yourself in the other cases:
+In _imperative_ mode, any event dispatched through a `TestElement` automatically calls `detectChanges()` for you.
+But you still need to call `change()` or `detectChanges()` by yourself in the other cases:
 
 - to actually initialize your component. Sometimes, you want to configure some mocks before the `ngOnInit()`
   method of your component is called. That's why creating a `ComponentTester` does not automatically call
@@ -553,6 +635,15 @@ But you still need to call `detectChanges()` by yourself in the other cases:
   by changing the state, or emitting an event through a subject, or triggering a navigation
   from the `ActivatedRouteStub`
 
+Note that, in _imperative_ mode, `change()` calls `detectChanges()`. So you can call either one of the other
+when you want to trigger a change detection.
+
+In _automatic_ mode, any event dispatched through a `TestElement` automatically calls `await change()` for you.
+But you still need to call `await change()` by yourself in the same other cases as in the _imperative_ mode:
+
+- to actually initialize your component. 
+- to force change detection once you've changed the state of your component without dispatching an event.
+
 ### Can I use the `TestElement` methods to act on the component element itself, rather than a sub-element?
 
 Yes. The `ComponentTester` has a `testElement` property, which is the `TestHtmlElement` wrapping the component's element.
@@ -564,3 +655,53 @@ Please, provide feedback by filing issues, or by submitting pull requests, to th
 ## Complete example
 
 You can look at a minimal complete example in the [demo](https://github.com/Ninja-Squad/ngx-speculoos/tree/master/projects/demo/src/app) project.
+
+## Upgrading to v13
+
+Version 13 of `ngx-speculoos` introduces the _automatic_ mode, consisting in using automatic change detection
+instead of imperatively running change detections. See the [Automatic change detection](#automatic-change-detection)
+section above for details.
+
+As a result, all the methods that used to call `detectChanges()` for you now return a `Promise` instead of returning
+`void`. In _imperative_ mode (the default), they are in fact synchronous and call `detectChanges()`, just as before.
+In _automatic_ mode however, they call `await change()` and should thus be awaited.
+
+Your tests should generally keep compiling and running without changes. 
+But if you created custom test elements which override methods that now return a promise, and return something 
+other than `void`, for example:
+
+```typescript
+class CustomInput extends TestInput {
+  //...
+  fillWith(s: string): CustomInput {
+    super.fillWith(s);
+    return this;
+  }
+}
+```
+
+Then that won't compile anymore.
+
+And in general, if you want your custom test element to be usable in both modes, all their method that explicitly
+or indirectly called `detectChanges()` should now return a promise and explicitly of indirectly call `await change()`.
+For example:
+
+```typescript
+class CustomInput extends TestHtmlElement {
+  //...
+  async fillInput(s: string): Promise<void> {
+    await this.element('input').fillWith(s);
+    // ...
+  }
+  
+  async clickButton(): Promise<void> {
+    await this.element('button').click();
+    // ...
+  } 
+  
+  async changeState(): Promise<void> {
+    this.component(Foo).doSomething();
+    await this.change();
+  }
+}
+```

package/fesm2022/ngx-speculoos.mjs

@@ -1,13 +1,19 @@
-import { TestBed, ComponentFixture } from '@angular/core/testing';
+import { TestBed, ComponentFixture, ComponentFixtureAutoDetect } from '@angular/core/testing';
 import { By } from '@angular/platform-browser';
 import { RouterTestingHarness } from '@angular/router/testing';
 import { Router, ActivatedRouteSnapshot, convertToParamMap, ActivatedRoute } from '@angular/router';
 import { BehaviorSubject } from 'rxjs';
+import { makeEnvironmentProviders } from '@angular/core';
+
+"use strict";
 
 /**
  * A wrapped DOM element, providing additional methods and attributes helping with writing tests
  */
 class TestElement {
+    tester;
+    debugElement;
+    querier;
     constructor(tester, 
     /**
      * the wrapped debug element
@@ -29,16 +35,16 @@ class TestElement {
     /**
      * dispatches an event of the given type from the wrapped element, then triggers a change detection
      */
-    dispatchEventOfType(type) {
+    async dispatchEventOfType(type) {
         this.nativeElement.dispatchEvent(new Event(type));
-        this.tester.detectChanges();
+        await this.tester.change();
     }
     /**
      * dispatches the given event from the wrapped element, then triggers a change detection
      */
-    dispatchEvent(event) {
+    async dispatchEvent(event) {
         this.nativeElement.dispatchEvent(event);
-        this.tester.detectChanges();
+        await this.tester.change();
     }
     /**
      * Gets the CSS classes of the wrapped element, as an array
@@ -155,9 +161,9 @@ class TestHtmlElement extends TestElement {
     /**
      * Clicks on the wrapped element, then triggers a change detection
      */
-    click() {
+    async click() {
         this.nativeElement.click();
-        this.tester.detectChanges();
+        await this.tester.change();
     }
     /**
      * Tests if the element is visible, in the same meaning (and implementation) as in jQuery, i.e.
@@ -200,7 +206,7 @@ class TestSelect extends TestHtmlElement {
             throw new Error(`The index ${index} is out of bounds`);
         }
         this.nativeElement.selectedIndex = index;
-        this.dispatchEventOfType('change');
+        return this.dispatchEventOfType('change');
     }
     /**
      * Selects the first option with the given value, then dispatches an event of type change and triggers a change detection.
@@ -209,7 +215,7 @@ class TestSelect extends TestHtmlElement {
     selectValue(value) {
         const index = this.optionValues.indexOf(value);
         if (index >= 0) {
-            this.selectIndex(index);
+            return this.selectIndex(index);
         }
         else {
             throw new Error(`The value ${value} is not part of the option values (${this.optionValues.join(', ')})`);
@@ -222,7 +228,7 @@ class TestSelect extends TestHtmlElement {
     selectLabel(label) {
         const index = this.optionLabels.indexOf(label);
         if (index >= 0) {
-            this.selectIndex(index);
+            return this.selectIndex(index);
         }
         else {
             throw new Error(`The label ${label} is not part of the option labels (${this.optionLabels.join(', ')})`);
@@ -289,9 +295,9 @@ class TestTextArea extends TestHtmlElement {
      * Sets the value of the wrapped textarea, then dispatches an event of type input and triggers a change detection
      * @param value the new value of the textarea
      */
-    fillWith(value) {
+    async fillWith(value) {
         this.nativeElement.value = value;
-        this.dispatchEventOfType('input');
+        await this.dispatchEventOfType('input');
     }
     /**
      * the value of the wrapped textarea
@@ -318,9 +324,9 @@ class TestInput extends TestHtmlElement {
      * Sets the value of the wrapped input, then dispatches an event of type input and triggers a change detection
      * @param value the new value of the input
      */
-    fillWith(value) {
+    async fillWith(value) {
         this.nativeElement.value = value;
-        this.dispatchEventOfType('input');
+        await this.dispatchEventOfType('input');
     }
     /**
      * the value of the wrapped input
@@ -343,16 +349,16 @@ class TestInput extends TestHtmlElement {
     /**
      * Checks the wrapped input, then dispatches an event of type change and triggers a change detection
      */
-    check() {
+    async check() {
         this.nativeElement.checked = true;
-        this.dispatchEventOfType('change');
+        await this.dispatchEventOfType('change');
     }
     /**
      * Unchecks the wrapped input, then dispatches an event of type change and triggers a change detection
      */
-    uncheck() {
+    async uncheck() {
         this.nativeElement.checked = false;
-        this.dispatchEventOfType('change');
+        await this.dispatchEventOfType('change');
     }
 }
 
@@ -361,6 +367,8 @@ class TestInput extends TestHtmlElement {
  * @internal
  */
 class TestElementQuerier {
+    tester;
+    root;
     constructor(tester, root) {
         this.tester = tester;
         this.root = root;
@@ -497,6 +505,18 @@ class TestElementQuerier {
  * @param <C> the type of the component to test
  */
 class ComponentTester {
+    /**
+     * The test element of the component
+     */
+    testElement;
+    /**
+     * The component fixture of the component
+     */
+    fixture;
+    /**
+     * The mode used by the ComponentTester
+     */
+    mode;
     /**
      * Creates a component fixture of the given type with the TestBed and wraps it into a ComponentTester
      */
@@ -517,7 +537,9 @@ class ComponentTester {
      */
     constructor(arg) {
         this.fixture = arg instanceof ComponentFixture ? arg : TestBed.createComponent(arg);
+        const autoDetect = TestBed.inject(ComponentFixtureAutoDetect, false);
         this.testElement = TestElementQuerier.wrap(this.debugElement, this);
+        this.mode = autoDetect ? 'automatic' : 'imperative';
     }
     /**
      * The native DOM host element of the component
@@ -627,17 +649,36 @@ class ComponentTester {
         return this.testElement.customs(selector, customTestElementType);
     }
     /**
-     * Triggers a change detection using the wrapped fixture
+     * Triggers a change detection using the wrapped fixture in imperative mode.
+     * Throws an error in autodetection mode.
+     * You should generally prever
      */
     detectChanges(checkNoChanges) {
+        if (this.mode === 'automatic') {
+            throw new Error('In automatic mode, you should not call detectChanges');
+        }
         this.fixture.detectChanges(checkNoChanges);
     }
     /**
-     * Delegates to the wrapped fixture whenStable and then detect changes
+     * In imperative mode, runs change detection.
+     * In implicit mode, awaits stability.
+     */
+    async change() {
+        if (this.mode === 'automatic') {
+            await this.stable();
+        }
+        else {
+            this.fixture.detectChanges();
+        }
+    }
+    /**
+     * Delegates to the wrapped fixture whenStable and, in imperative mode, detect changes
      */
     async stable() {
         await this.fixture.whenStable();
-        this.detectChanges();
+        if (this.mode === 'imperative') {
+            this.detectChanges();
+        }
     }
 }
 
@@ -649,6 +690,7 @@ class ComponentTester {
  * for example.
  */
 class RoutingTester extends ComponentTester {
+    harness;
     constructor(harness) {
         super(harness.fixture);
         this.harness = harness;
@@ -681,6 +723,12 @@ class RoutingTester extends ComponentTester {
 }
 
 class ActivatedRouteSnapshotStub extends ActivatedRouteSnapshot {
+    _parent = null;
+    _root;
+    _firstChild = null;
+    _children = [];
+    _pathFromRoot = [];
+    _title;
     get parent() {
         return this._parent;
     }
@@ -725,10 +773,6 @@ class ActivatedRouteSnapshotStub extends ActivatedRouteSnapshot {
     }
     constructor() {
         super();
-        this._parent = null;
-        this._firstChild = null;
-        this._children = [];
-        this._pathFromRoot = [];
         this._root = this;
     }
 }
@@ -749,6 +793,17 @@ class ActivatedRouteSnapshotStub extends ActivatedRouteSnapshot {
  *   on the stub route. So if the code keeps a reference to params or paramMaps, it won't see the changes.
  */
 class ActivatedRouteStub extends ActivatedRoute {
+    _firstChild;
+    _children;
+    paramsSubject;
+    queryParamsSubject;
+    dataSubject;
+    fragmentSubject;
+    urlSubject;
+    titleSubject;
+    _parent;
+    _root;
+    _pathFromRoot;
     /**
      * Constructs a new instance, based on the given options.
      * If an option is not provided (or if no option is provided at all), then the route has a default value for this option
@@ -1249,15 +1304,30 @@ function createMock(type) {
     return jasmine.createSpyObj(type.name, collectMethodNames(type.prototype));
 }
 
+const COMPONENT_FIXTURE_AUTO_DETECTION = makeEnvironmentProviders([
+    { provide: ComponentFixtureAutoDetect, useValue: true }
+]);
+/**
+ * Provide function which returns the provider `{ provide: ComponentFixtureAutoDetect, useValue: true }`.
+ * This provider can be added to the testing module to configure the component testers
+ * (and the underlying ComponentFixture) in automatic mode:
+ *
+ * ```
+ * TestBed.configureTestingModule({ providers: [provideAutomaticChangeDetection()] });
+ * ```
+ */
+function provideAutomaticChangeDetection() {
+    return COMPONENT_FIXTURE_AUTO_DETECTION;
+}
+
 /* eslint-disable */
 /*
  * Public API Surface of ngx-speculoos
  */
-/// <reference path="./jasmine-matchers.ts" />
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { ActivatedRouteStub, ComponentTester, RoutingTester, TestButton, TestElement, TestHtmlElement, TestInput, TestSelect, TestTextArea, createMock, speculoosMatchers, stubRoute };
+export { ActivatedRouteStub, ComponentTester, RoutingTester, TestButton, TestElement, TestHtmlElement, TestInput, TestSelect, TestTextArea, createMock, provideAutomaticChangeDetection, speculoosMatchers, stubRoute };
 //# sourceMappingURL=ngx-speculoos.mjs.map