[Feature]: Add `toBeReactivePure` matcher

[MillerSvt]

🚀 Feature Proposal

Sometimes, when working with functions that use signals, we need to ensure that our function is reactive pure. This means that if any methods or effects call this function, it should not have any side effects based on the signal. To achieve this, I propose adding a special matcher, such as the toThrow matcher.

Motivation

I believe that having the option to check for reactive purity could help Angular developers become more responsible when working with reactive functions.

Possible solution

declare global {
	namespace jest {
		interface Matchers<R> {
			toBeReactivePure: () => R;
		}
	}
}

expect.extend({
	toBeReactivePure: function (
		this: jest.MatcherContext,
		fn: () => void,
	): jest.CustomMatcherResult {
		const reactiveNode: ReactiveNode = Object.create(REACTIVE_NODE);
		const prevConsumer = setActiveConsumer(reactiveNode);

		reactiveNode.consumerAllowSignalWrites = true;

		try {
			fn();
		} finally {
			setActiveConsumer(prevConsumer);
		}

		if (reactiveNode.producerNode?.length) {
			return {
				message: () =>
					`Expected to be reactive pure: Found ${reactiveNode.producerNode?.length} producers`,
				pass: false,
			};
		}

		return {
			message: () => `Expected to be not reactive pure`,
			pass: true,
		};
	},
});

Usage

it('should not register producers on consumer in reactive context when updating signal', () => {
	const customSignal = customSignal('');

	expect(() => {
		customSignal.set(newValue1);
		customSignal.update(() => newValue2);
	}).toBeReactivePure();
});

Real world example: ngxtension/ngxtension-platform#593

Additional

I can create pr with that

[ahnpnl]

Do we have examples how this matcher would be useful when testing for components/services/pipes/directives?

It would be good that the matcher is not limited to test only for functions.

[MillerSvt]

The methods of components, directives, and pipes are also functions.

[ahnpnl]

Lets hold off this one for now until there are more needed on this. As far as I can see in my work projects, this matcher is hardly needed anywhere