feat(core): add an utils waitForSignal

Add a utils function `waitForSignal` that is helping to wait the value of the signal to fulfill a condition provided in parameter (or be truthly).

Author: ExFlo

packages/core/test/async_spec.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {Injector, signal} from '../public_api';
+import {TestBed, waitForSignal} from '../testing/public_api';
+
+describe('async', () => {
+ it('should resolve directly if the signal value is truthy', async () => {
+ const sig = signal(true);
+ const result = waitForSignal(sig);
+ await expectAsync(result).toBeResolvedTo(true);
+ const sig2 = signal('truthy');
+ const result2 = waitForSignal(sig2);
+ await expectAsync(result2).toBeResolvedTo('truthy');
+ });
+
+ it('should be rejected after timeout millisecond', async () => {
+ const sig = signal(true);
+ const testFn = (value: boolean) => {
+ return value === false;
+ };
+ const result = waitForSignal(sig, testFn, {timeout: 100});
+ await expectAsync(result).toBeRejected();
+ });
+
+ it('should be resolve correctly when the signal reach the correct value', async () => {
+ const sig = signal(true);
+ const testFn = (value: boolean) => {
+ return value === false;
+ };
+ const result = waitForSignal(sig, testFn, {timeout: 1000});
+ setTimeout(() => {
+ sig.set(false);
+ }, 500);
+
+ await expectAsync(result).toBeResolvedTo(false);
+ });
+
+ it('should be rejected when signal is destroyed', async () => {
+ const sig = signal(false);
+ let result: Promise<boolean>;
+
+ const inj = Injector.create({
+ providers: [],
+ parent: TestBed.inject(Injector),
+ });
+ result = waitForSignal(sig, undefined, {timeout: 1000, injector: inj});
+ setTimeout(() => {
+ sig.set(true);
+ }, 500);
+ inj.destroy();
+ await expectAsync(result).toBeRejected();
+ });
+});

packages/core/testing/src/async.ts

@@ -5,6 +5,10 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
+
+import {DestroyRef, effect, inject, Injector, Signal} from '../../src/core';
+import {TestBedImpl} from './test_bed';
+
 /**
  * Wraps a test function in an asynchronous test zone. The test will automatically
  * complete when all asynchronous calls within this zone are done. Can be used
@@ -43,3 +47,80 @@ export function waitForAsync(fn: Function): (done: any) => any {
  );
  };
 }
+
+/**
+ * Options for `WaitForSignalOptions`.
+ *
+ * @publicApi
+ */
+export interface WaitForSignalOptions {
+ /**
+ * The `Injector` to use when creating the underlying `effect` which watches the signal.
+ *
+ * If this isn't specified, the TestBed injector will be used
+ */
+ injector?: Injector;
+ /**
+ * The timeout value in millisecond
+ */
+ timeout?: number;
+}
+
+/**
+ * Utils to wait for a specific condition fulfilled by a Signal's value.
+ * By default, it will wait for the signal to be truthy.
+ * This is useful when you want to wait for a signal to be in a specific state during your unit tests.
+ *
+ * @param source The Signal to watch for the test condition.
+ * @param testFn The function called with the source value each time the source changes. It should return true when the condition expected is fulfilled.
+ * @param options The options to provide both
+ * - the injector to use when creating the underlying effect which watches the signal.
+ *
+ * If this isn't specified, the TestBed injector will be used
+ *
+ * - the timeout value in millisecond. After this time the watcher will be destroyed and the Promise rejected.
+ * Default value is 10000.
+ *
+ * @usageNotes
+ *
+ * `waitForSignal` must be called in a test context.
+ *
+ * @returns The Promise<T> that will be resolved with the signal value when the testFn is returning true.
+ *
+ * @publicApi
+ */
+export function waitForSignal<T>(
+ source: Signal<T>,
+ testFn: (value: T) => boolean = (value) => !!value,
+ options?: WaitForSignalOptions,
+): Promise<T> {
+ const injector = options?.injector ?? TestBedImpl.INSTANCE.inject(Injector);
+
+ const promise = new Promise<T>((resolve, reject) => {
+ const watcher = effect(
+ () => {
+ let value: T;
+ try {
+ value = source();
+ if (testFn(value)) {
+ resolve(value);
+ cleanUpFn();
+ }
+ } catch (err) {}
+ },
+ {injector, manualCleanup: true},
+ );
+ let cleanUpFn = () => {
+ reject();
+ clearTimeout(overallTimeoutTimer);
+ watcher.destroy();
+ destroyFn();
+ };
+
+ const overallTimeoutTimer = setTimeout(cleanUpFn, options?.timeout ?? 10000);
+
+ const destroyFn = injector.get(DestroyRef).onDestroy(cleanUpFn);
+ });
+
+ return promise;
+}