feat: support assertion extensions in harnesses

JulianLang · JulianLang · commit a26ef963ef22 · 2025-02-01T23:50:02.000+01:00
diff --git a/docs/scenario-testing/vision.md b/docs/scenario-testing/vision.md
@@ -14,4 +14,4 @@
 
 ## Vision
 
-TODO: explain feature: scenario based test generation
+TODO: docs: explain feature: scenario based test generation
diff --git a/library/scenario-testing/scenario-harnesses.ts b/library/scenario-testing/scenario-harnesses.ts
@@ -5,7 +5,7 @@ import { TypedDebugElement, UnwrapSignals } from '../types';
 import { isNgtxQuerySelector } from '../utility';
 import { NgtxScenarioTestEnvironment } from './scenario-testing';
 import { NgtxScenarioTestIsAssertionNegated } from './symbols';
-import { ComponentFixtureRef } from './types';
+import { ComponentFixtureRef, NgtxScenarioTestAssertionFn } from './types';
 
 export class ScenarioTestingHarnessBase<Html extends HTMLElement, Component> {
   private [NgtxScenarioTestIsAssertionNegated] = false;
@@ -16,7 +16,7 @@ export class ScenarioTestingHarnessBase<Html extends HTMLElement, Component> {
 
   public readonly not: Omit<typeof this, 'not'> = new Proxy(this, {
     get: (_, property) => {
-      // TODO: document that constructors of Harnesses are not allowed to be overridden!
+      // TODO: docs: document that constructors of Harnesses are not allowed to be overridden!
       const harnessConstructor = this.constructor as any;
       const target = new harnessConstructor(
         this.selector,
@@ -243,4 +243,8 @@ export class ScenarioTestingHarness<
       );
     });
   }
+  public to(...assertions: NgtxScenarioTestAssertionFn<Html, Component>[]) {
+    const addTests: typeof this.addTests = this.addTests.bind(this);
+    return assertions.map((assertion) => assertion(addTests, this));
+  }
 }
diff --git a/library/scenario-testing/scenario-testing.ts b/library/scenario-testing/scenario-testing.ts
@@ -130,7 +130,9 @@ export class NgtxTestScenario<T = any> {
     return scenario;
   }
 
-  expect(...tests: ScenarioTestDefinition<T>[]): void {
+  expect(
+    ...tests: (ScenarioTestDefinition<T> | ScenarioTestDefinition<T>[])[]
+  ): void {
     const scenario = NgtxTestScenario.from(
       {
         componentType: this._componentType,
@@ -140,7 +142,7 @@ export class NgtxTestScenario<T = any> {
           this._modificationsBeforeComponentCreation,
         modificationsAfterComponentCreation:
           this._modificationsAfterComponentCreation,
-        tests: [...this.tests, ...tests],
+        tests: [...this.tests, ...tests].flat(1),
       },
       this._testEnvironment,
     );
diff --git a/library/scenario-testing/types.ts b/library/scenario-testing/types.ts
@@ -1,5 +1,6 @@
 import { Type } from '@angular/core';
 import { ComponentFixture, TestModuleMetadata } from '@angular/core/testing';
+import { ScenarioTestingHarness } from './scenario-harnesses';
 import {
   NgtxScenarioSetupFnMarker,
   NgtxScenarioViewSetupFnMarker,
@@ -34,3 +35,8 @@ export type ScenarioViewSetupFn<T> = ((
 export type ScenarioSetupFn = (() => void) & {
   [NgtxScenarioSetupFnMarker]: boolean;
 };
+
+export type NgtxScenarioTestAssertionFn<Html extends HTMLElement, Component> = (
+  addTests: ScenarioTestingHarness<Html, Component>['addTests'],
+  harness: ScenarioTestingHarness<Html, Component>,
+) => ScenarioTestDefinition<any>;
diff --git a/library/specs/scenario/scenario-testing.spec.ts b/library/specs/scenario/scenario-testing.spec.ts
@@ -4,6 +4,7 @@ import { ActivatedRoute, RouterModule } from '@angular/router';
 import { ngtx } from '../../ngtx';
 import { ScenarioTestingHarness } from '../../scenario-testing/scenario-harnesses';
 import { useScenarioTesting } from '../../scenario-testing/scenario-testing';
+import { NgtxScenarioTestAssertionFn } from '../../scenario-testing/types';
 
 @Injectable()
 class MyService {
@@ -57,7 +58,11 @@ const withServiceState = <T>(token: Type<T>, state: Partial<T>) =>
 // Usage Example
 // ----------------------------
 
-const { scenario, expect, tests } = useScenarioTesting({
+const {
+  scenario,
+  expect: expectThat,
+  tests,
+} = useScenarioTesting({
   componentType: ScenarioTestComponent,
   moduleConfig: {
     imports: [RouterModule.forRoot([])],
@@ -110,16 +115,31 @@ scenario(`The param id is 42`)
     the.ParamIdDiv.toHaveAttributes({ title: 42 }),
   );
 
-expect(
+expectThat(
   the.Div.toBeFound(),
   the.ParamIdDiv.toBeMissing(),
   the.Text.toHaveState({ text: 'Hello, World!' }),
 );
 
-expect(
+const beComponentType =
+  (type: any): NgtxScenarioTestAssertionFn<HTMLElement, any> =>
+  // TODO: docs: document that debugElement must only be accessed within it case:
+  (addTests, harness) =>
+    addTests(() => {
+      it(`should be the component "${type.name}"`, () => {
+        expect(harness.debugElement.componentInstance).toBeInstanceOf(type);
+      });
+    });
+
+expectThat(
   the.Div.toBeFound(),
   the.ParamIdDiv.toBeMissing(),
   the.Text.toHaveState({ text: 'Hello, World!' }),
+  the.Text.to(
+    beComponentType(TextComponent),
+    beComponentType(TextComponent),
+    beComponentType(TextComponent),
+  ),
 );
 
 tests.run();

Original file line number	Diff line number	Diff line change
`@@ -14,4 +14,4 @@`
`14`	`14`
`15`	`15`	`## Vision`
`16`	`16`
`17`		`-TODO: explain feature: scenario based test generation`
	`17`	`+TODO: docs: explain feature: scenario based test generation`