Improve Angular Testing Library API documentation

[ChristophWalter]

I am new to Angular Testing and stumbled across some misunderstandings while writing my first tests. I would like to help you improve it, so let's start collecting the issues. 🙂

1. The example for the declarations (within RenderOptions) is wrong. It configures the providers. Furthermore there is no descriptions for the providers option. https://testing-library.com/docs/angular-testing-library/api#declarations
2. We might also add a note which of the RenderOptions are passed to the Angular TestBed. Or even separate those from the added render properties.
3. Explaining that this library still works with the core testing functionality of Angular under the hood will also help to implement non-standard situations. For example in one test I needed to interact with a service. This can be done with the Angular TestBed: TestBed.get(TargetService).init();

[timdeschryver]

Hi, I'm the maintainer of Angular Testing Library. Those are all valid points, feel free to create a PR and ping me for a review.

[shaman-apprentice]

What do you think about aligning the API behavior to React's API? I stumbled over rerender and first created a bug here as I was sure about my unchecked React-based assumptions:

In the React-world, rerender on a (legacy) class component, results in a call to render and a call to componentDidUpdate with previous props as parameters, but not to a call to constructor or componentDidMount.

On the other hand, in the Angular-world rerender does re-create the component from scratch. Meaning constructor is called again and ngOnChanges with initial simpleChange object without previous values / firstChange is set to true for each input property.

So my thoughts:

• From my React-based expectation I think Angular's rerender should do, what change does. But I am not sure if it is worth a breaking change?
• I am not sure if we need to replace the current behavior of rerender, as we can utilize render for creating a component from scratch, can we not?
• If we don't want to introduce a breaking change, I would like to create a PR to update rerender's description. Something along the lines of:

  Re-create the same component from scratch. ngOnChanges will be called with initial simple change object.

What do you think? Should I create an own issue for this discussion?

[timdeschryver]

@shaman-apprentice you can open a PR to update the docs. We can discuss this if we have more breaking changes, maybe soon because testing library dom is going to have some breaking changes

[shaman-apprentice]

@shaman-apprentice you can open a PR to update the docs. We can discuss this if we have more breaking changes, maybe soon because testing library dom is going to have some breaking changes

Thx! I created a PR with a suggestion for current behavior. Is there some process / guidelines how the api section of the docs should be aligned with the js docs from models.ts?

After some thoughts I still like the idea of the breaking change to remove change and let rerender do what change currently does. If you are open to this change, how should we proceed with this idea? Should I create a docs PR for it or maybe an own issue?

[timdeschryver]

@shaman-apprentice I try to keep it up-to-date, and I usually copy paste the content from the docs to the models (or the other way around). When the PR is merged, we can also update the models file.

For the breaking change, let's open an issue in ATL and discuss it there.