Improve Observables Testing documentation

📚 Docs or angular.io bug report

Description of the problem

Observables are a huge part of Angular.

Currently, the testing docs have examples on how to test Observable related code scattered across docs and we don’t have a dedicated place to learn about Observable testing.

A lot of examples are scattered around the docs and suggest either testing observables by subscribing (without unsubscribing BTW which is another issue), or showing how to test using marble tests, (and doing it only in the “components section” although it’s not limited only to components). And by that it seems like we’re jumping from the “easiest thing possible” straight to “having to know hot, cold, TestScheduler and look at all these signs!” type of tests (marble testing).

When there is a much simpler way to test Observables. It pretty new but very effective (according to people who used it in real life) and it’s called:

observer-spy

I created it a few months ago with the aim of reducing complexity when it comes to testing observables.

So although I’m biased, I waited a few months to see whether this open source library actually provides value to devs other than my clients before I thought about suggesting to add it to the docs.

So far it seems that it makes people lives’ easier.

For example, here are some of the responses I got since it got published -

---

---

---

---

Observer spies are much less complicated than marble testing and don’t require testing implementation details like knowing exactly how many frames passed between values (which normally you only care about the values and their order, rather than the time between them).

I believe marble testing should be the last topic we cover on Observable Testing to reduce the friction newcomers have when trying to learn Angular + testing, and to supply them with the simplest tools first before jumping into the more complicated ones 😅

Proposed Solution - a Dedicated “Observables Testing” Document

Because Observables are a cross cutting topic which can be found in all Angular types (services, components, etc), I believe it should have it’s own document called “Observables Testing”.

In there we should start by showing the simplest way (subscribing to get a value), then showing how to use observer-spies and with subscribeSpyTo and autoUnsubscribe (not to leave any leaks), the move to show how to auto-spy on dependencies which return observables and lastly - show how to test using marble tests.

The proposed table of contents:

1. An Observable Under Test - the easiest way
2. Testing multiple values - using observer spies
3. Faking dependencies with Observable returning methods
4. Marble Tests

I believe this would make the whole notion of Observable testing much easier to digest and get easy wins in both Angular and also NgRx code (like testing effects) and will help lower the entry barrier for testing Observables.

Let me know what you think. If we move forward, I could create a draft of the content and work with your documentation team to include it on Angular.io.

[jessicajaniuk]

@shairez Yes, as we shouldn’t be documenting it. It’ll get out of date as it’s not our library and is just a dependency. We’d also welcome a community PR to remove this documentation.

[angular-automatic-lock-bot[bot]]

This issue has been automatically locked due to inactivity. Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}