docs(signals): add testing guide #4461

rainerhahnekamp · 2024-07-26T09:41:46Z

PR Checklist

The formatted version is available at: https://github.com/rainerhahnekamp/ngrx/blob/docs/signals/testing/projects/ngrx.io/content/guide/signals/signal-store/testing.md.

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/ngrx/platform/blob/main/CONTRIBUTING.md#commit
Tests for the changes have been added (for bug fixes / features)
Documentation has been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Documentation content changes
[ ] Other... Please describe:

Closes #4206

Does this PR introduce a breaking change?

[ ] Yes
[x] No

netlify · 2024-07-26T09:42:02Z

✅ Deploy Preview for ngrx-io ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`df2912e`
🔍 Latest deploy log	https://app.netlify.com/sites/ngrx-io/deploys/66e89c8cd7b55300083f5d11
😎 Deploy Preview	https://deploy-preview-4461--ngrx-io.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

projects/ngrx.io/content/guide/signals/signal-store/testing.md

jdegand · 2024-08-01T17:56:22Z

Missing backtick on line 56 around TestBed. Some inconsistency in using TestBed and TestBed. Line 62 is missing the backticks.

Could add the links to ng-mocks and other libraries mentioned.

timdeschryver

I've added some thoughts on the structure of the page.
When the markdown is converted to a document page I'll go over it again and spent more time on style/grammar.

projects/ngrx.io/content/guide/signals/signal-store/testing.md

markostanimirovic · 2024-08-05T19:11:21Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+
+### On Testing in General
+
+A Signal Store is a simple Angular Service, so the same testing techniques you use for services apply to Signal Stores as well. This guide focuses on providing examples for common testing scenarios.


two minor suggestions to ensure consistency with the rest of the @ngrx/signals documentation:

Signal Store => SignalStore

Impersonal sentences

Not always a simple service 😅

Suggested change

A Signal Store is a simple Angular Service, so the same testing techniques you use for services apply to Signal Stores as well. This guide focuses on providing examples for common testing scenarios.

SignalStore is an Angular Service, so the same testing techniques used for services also apply to SignalStore.

markostanimirovic · 2024-08-05T19:18:22Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+
+A Signal Store is a simple Angular Service, so the same testing techniques you use for services apply to Signal Stores as well. This guide focuses on providing examples for common testing scenarios.
+
+A challenging part of testing is knowing how to handle asynchronous tasks and mocking. The examples use Jest (v29.5), but the same principles apply to other testing frameworks.


The main heading is missing in the beginning - # Testing. After the main title, we can put the second sentence from the previous section together with this:

# Testing This page contains examples of common testing scenarios with NgRx SignalStore. Examples use Jest, but the same principles apply to other testing frameworks. // ... subheadings and the rest of the content

Note that the exact Jest version is removed. It's not necessary in my opinion as we're using Jest APIs available in most of the recent versions but also to avoid this guide looks obsolete after new Jest releases.

projects/ngrx.io/content/guide/signals/signal-store/testing.md

markostanimirovic · 2024-08-05T19:45:20Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+
+</div>
+
+We use Jest's tools to manage asynchronous tasks. We avoid using `fakeAsync` or `waitForAsync` as they depend on zone.js and are incompatible with zoneless applications.


Do we know what's the status of Angular testing helpers - does the Angular team plan to deprecate them or provide Zoneless support when Zoneless mode becomes stable? If they don't plan to provide Zoneless support for the testing package, feel free to ignore my previous comment.

As an in-between strategy, they allowed detectChanges to be called with a zoneless fixture. See this PR.

I believe a fake Zone is created and used behind the scenes for zoneless apps.

This issue could be of good interest to watch. It pertains to timers and zoneless.

Another PR that could be relevant is that fakeAsync will now automatically flush.

Sorry, @markostanimirovic, I just spotted your comment here and answered the above.

I think we should get a clarification from the official side first and then decide if we stick to fakeAsync or go with the native ones.

markostanimirovic · 2024-08-05T20:02:55Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+})
+```
+
+This version requires that the test can modify the state, even if it is protected.


Suggested change

This version requires that the test can modify the state, even if it is protected.

This version requires the `MoviesStore` state to be unprotected.

markostanimirovic · 2024-08-05T20:07:20Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+
+This version requires that the test can modify the state, even if it is protected.
+
+We are currently evaluating options for test helpers that allow state modification for protected states without introducing new mocking features that are already covered by existing testing frameworks.


This sentence can be removed from the official guide. Opening an issue on this topic would be a better option in my opinion.

markostanimirovic · 2024-08-05T20:08:36Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+
+We are currently evaluating options for test helpers that allow state modification for protected states without introducing new mocking features that are already covered by existing testing frameworks.
+
+Additionally, there is a community project by Gergely Szerovay that provides a comprehensive mocking library for Signal Stores. You can find more details here: https://www.angularaddicts.com/p/how-to-mock-ngrx-signal-stores


Same here. To keep this guide concise, we can add the "Community Plugins" page and share community work there.

markostanimirovic · 2024-08-05T20:19:13Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

@@ -0,0 +1,687 @@
+<!-- TOC -->


To make this page visible in the side nav, we should add link to the navigation.json: https://github.com/ngrx/platform/blob/main/projects/ngrx.io/content/navigation.json#L311

markgoho · 2024-08-08T21:00:49Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+There are two main scenarios for testing:
+
+1. Testing the `signalStore` itself,
+2. Testing a component or service that uses the Signal Store.
+
+In the first scenario, you’ll mock the dependencies of the Signal Store, while in the second scenario, you’ll mock the Signal Store itself.


There is a third scenario where we test the service by:

creating a testing component

injecting the service

mocking only the service dependencies (not the signal store)

In this way, we can make assertions about what user behavior the service provides without testing the implementation details of the service.

Scenario one above tests pure implementation details and tells us very little about how the service will be used alongside user behavior. Scenario two above tests user behavior, but depending on how broad the scope of the service is may not result in 100% coverage of the branches/functions/etc of the service in that single component.

I think there's a good opportunity to present an opinion about how services can be tested in general (via this third scenario).

I think Tim is hinting at this in his comment about integration testing but I don't want to put words in his mouth

Yes, I thought it is not necessary, but you two have convinced me. I will add it.

rainerhahnekamp · 2024-09-08T23:54:56Z

@markostanimirovic, @timdeschryver, @jdegand, @markgoho

I've incorporated all your suggestions and left them open for your convenience. I'm now ready for the next review round and promise it will be faster as the first one. 😄

brandonroberts · 2024-09-09T16:28:23Z

The formatting on some of the code snippets is a little off, but I think in general its ready to be merged, and we can follow up with additional PRs with more cleanup.

projects/ngrx.io/content/guide/signals/signal-store/testing.md

jdegand · 2024-09-10T05:25:35Z

projects/ngrx.io/content/guide/signals/signal-store/testing.md

+  const fixture = TestBed.createComponent(MoviesComponent);
+  fixture.autoDetectChanges(true);
+
+  const studio = load.mock.calls[0][0];


I think this might be wrong. Only one [0] ?

[0][0] means the first parameter of the first call.

Yes, you are right. mock.calls returns an array of arrays.

timdeschryver · 2024-09-11T17:41:18Z

@markostanimirovic, @timdeschryver, @jdegand, @markgoho

I've incorporated all your suggestions and left them open for your convenience. I'm now ready for the next review round and promise it will be faster as the first one. 😄

Thanks @rainerhahnekamp 🙏
I will go through this later this week (probably over the weekend)

markostanimirovic

I fixed formatting and issues with angle brackets.

There is room for improvement. For example, some code snippets are too long.

We can merge the testing guide as is for now and improve it later.

timdeschryver

I left some grammar notes, for the rest it looks good and I like the structure you gave it.
(I agree with Marko's comment)

projects/ngrx.io/content/guide/signals/signal-store/testing.md

Co-authored-by: Tim Deschryver <[email protected]>

rainerhahnekamp · 2024-09-16T21:01:27Z

Thanks @timdeschryver

timdeschryver

Thanks @rainerhahnekamp !

markostanimirovic reviewed Jul 29, 2024

View reviewed changes

projects/ngrx.io/content/guide/signals/signal-store/testing.md Outdated Show resolved Hide resolved

rainerhahnekamp mentioned this pull request Aug 1, 2024

Add testing guide for NgRx SignalStore #4206

Closed

2 tasks

rainerhahnekamp marked this pull request as ready for review August 1, 2024 12:18

timdeschryver reviewed Aug 5, 2024

View reviewed changes

markostanimirovic requested changes Aug 5, 2024

View reviewed changes

markostanimirovic reviewed Aug 5, 2024

View reviewed changes

markgoho reviewed Aug 8, 2024

View reviewed changes

ghost approved these changes Aug 24, 2024

View reviewed changes

brandonroberts approved these changes Sep 9, 2024

View reviewed changes

jdegand reviewed Sep 10, 2024

View reviewed changes

projects/ngrx.io/content/guide/signals/signal-store/testing.md Outdated Show resolved Hide resolved

jdegand reviewed Sep 10, 2024

View reviewed changes

rainerhahnekamp added 8 commits September 10, 2024 23:51

docs(signals): add testing guide

d5f989b

docs: first rough draft

e343073

docs: improve

f767184

docs: add spy version

f19dbf3

docs: improve wording

70d3bda

docs: improve

711b498

docs: incooperate feedback from review

f3fb9bb

docs: add missing semi-colons

d3b02f9

rainerhahnekamp force-pushed the docs/signals/testing branch from 7cdf4ce to d3b02f9 Compare September 10, 2024 21:58

markostanimirovic added 2 commits September 16, 2024 01:42

fix formatting

13c505b

fix angle brackets

5dfb7bc

markostanimirovic approved these changes Sep 16, 2024

View reviewed changes

markostanimirovic assigned timdeschryver Sep 16, 2024

timdeschryver reviewed Sep 16, 2024

View reviewed changes

markgoho approved these changes Sep 16, 2024

View reviewed changes

rainerhahnekamp and others added 5 commits September 16, 2024 23:00

Update projects/ngrx.io/content/guide/signals/signal-store/testing.md

0869062

Co-authored-by: Tim Deschryver <[email protected]>

Update projects/ngrx.io/content/guide/signals/signal-store/testing.md

030f861

Co-authored-by: Tim Deschryver <[email protected]>

Update projects/ngrx.io/content/guide/signals/signal-store/testing.md

e9b3753

Co-authored-by: Tim Deschryver <[email protected]>

Update projects/ngrx.io/content/guide/signals/signal-store/testing.md

f7082df

Co-authored-by: Tim Deschryver <[email protected]>

Update projects/ngrx.io/content/guide/signals/signal-store/testing.md

df2912e

Co-authored-by: Tim Deschryver <[email protected]>

markostanimirovic requested a review from timdeschryver September 16, 2024 22:56

timdeschryver approved these changes Sep 17, 2024

View reviewed changes

timdeschryver merged commit 1f7f740 into ngrx:main Sep 17, 2024
11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(signals): add testing guide #4461

docs(signals): add testing guide #4461

rainerhahnekamp commented Jul 26, 2024 •

edited

Loading

netlify bot commented Jul 26, 2024 •

edited

Loading

jdegand commented Aug 1, 2024

timdeschryver left a comment

markostanimirovic Aug 5, 2024

markostanimirovic Aug 5, 2024

markostanimirovic Aug 5, 2024

jdegand Aug 6, 2024

rainerhahnekamp Aug 12, 2024

markostanimirovic Aug 5, 2024

markostanimirovic Aug 5, 2024

markostanimirovic Aug 5, 2024

markostanimirovic Aug 5, 2024

markgoho Aug 8, 2024

rainerhahnekamp Aug 8, 2024

rainerhahnekamp commented Sep 8, 2024

brandonroberts commented Sep 9, 2024

jdegand Sep 10, 2024 •

edited

Loading

rainerhahnekamp Sep 10, 2024

jdegand Sep 11, 2024

timdeschryver commented Sep 11, 2024

markostanimirovic left a comment •

edited

Loading

timdeschryver left a comment

rainerhahnekamp commented Sep 16, 2024

timdeschryver left a comment


		### On Testing in General

		A Signal Store is a simple Angular Service, so the same testing techniques you use for services apply to Signal Stores as well. This guide focuses on providing examples for common testing scenarios.

	A Signal Store is a simple Angular Service, so the same testing techniques you use for services apply to Signal Stores as well. This guide focuses on providing examples for common testing scenarios.
	SignalStore is an Angular Service, so the same testing techniques used for services also apply to SignalStore.


		A Signal Store is a simple Angular Service, so the same testing techniques you use for services apply to Signal Stores as well. This guide focuses on providing examples for common testing scenarios.

		A challenging part of testing is knowing how to handle asynchronous tasks and mocking. The examples use Jest (v29.5), but the same principles apply to other testing frameworks.


		</div>

		We use Jest's tools to manage asynchronous tasks. We avoid using `fakeAsync` or `waitForAsync` as they depend on zone.js and are incompatible with zoneless applications.

	This version requires that the test can modify the state, even if it is protected.
	This version requires the `MoviesStore` state to be unprotected.


		This version requires that the test can modify the state, even if it is protected.

		We are currently evaluating options for test helpers that allow state modification for protected states without introducing new mocking features that are already covered by existing testing frameworks.


		We are currently evaluating options for test helpers that allow state modification for protected states without introducing new mocking features that are already covered by existing testing frameworks.

		Additionally, there is a community project by Gergely Szerovay that provides a comprehensive mocking library for Signal Stores. You can find more details here: https://www.angularaddicts.com/p/how-to-mock-ngrx-signal-stores

docs(signals): add testing guide #4461

docs(signals): add testing guide #4461

Conversation

rainerhahnekamp commented Jul 26, 2024 • edited Loading

PR Checklist

PR Type

Does this PR introduce a breaking change?

netlify bot commented Jul 26, 2024 • edited Loading

✅ Deploy Preview for ngrx-io ready!

jdegand commented Aug 1, 2024

timdeschryver left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rainerhahnekamp commented Sep 8, 2024

brandonroberts commented Sep 9, 2024

jdegand Sep 10, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timdeschryver commented Sep 11, 2024

markostanimirovic left a comment • edited Loading

Choose a reason for hiding this comment

timdeschryver left a comment

Choose a reason for hiding this comment

rainerhahnekamp commented Sep 16, 2024

timdeschryver left a comment

Choose a reason for hiding this comment

rainerhahnekamp commented Jul 26, 2024 •

edited

Loading

netlify bot commented Jul 26, 2024 •

edited

Loading

jdegand Sep 10, 2024 •

edited

Loading

markostanimirovic left a comment •

edited

Loading