DOCSEARCHbyAlgolia
Submit Docs

Angular Testing Library

repository·main·Indexed 21 days ago

https://github.com/testing-library/angular-testing-library

A lightweight testing utility for Angular that encourages testing components based on user interaction and DOM nodes rather than internal implementation details. It provides utilities like render, screen, and fireEvent, and integrates with @testing-library/dom. The library includes support for Jest and Vitest, a migrate-to-zoneless schematic, and jest-utils for creating mock instances via createMock and provideMock.

Tokens
8.5K
Snippets
30
Records
42
Agent score
73%

What's inside @testing-library/angular

  2. How @testing-library/angular works

    main

    The library provides lightweight utility functions built on top of Angular and @testing-library/dom. It is designed to encourage testing practices that avoid implementation details and focus on how the software is actually used by a user.

    Guiding Principles:

    1. DOM-centric: Utilities deal with DOM nodes rather than component instances to ensure tests resemble user interaction.
    2. Versatile: Tools are useful for testing both individual components and full Angular applications.
    3. Simple & Flexible: APIs are designed to be lightweight and easy to understand.

  3. Run the Angular Testing Library example tests

    main

    To run the example tests provided in this repository, follow these steps:

    1. Clone or download the repository.
    2. Navigate into the repository directory.
    3. Install dependencies using npm install.
    4. Execute the tests using the Nx command: npx nx test example-app.

    Note: The examples in this repository are configured to use Jest, but the patterns are applicable to any test runner you choose to use.

    npm install
npx nx test example-app

  5. Install @testing-library/angular

    main

    You can install @testing-library/angular as a development dependency using npm. Note that starting from ATL version 17, you must also install @testing-library/dom.

    Alternatively, you can use the Angular CLI ng add command, which automatically handles the installation of both @testing-library/angular and @testing-library/dom.

    # Using npm
npm install --save-dev @testing-library/angular @testing-library/dom

# Using Angular CLI
ng add @testing-library/angular

  7. Run the Angular Testing Library example app

    main

    To run the example tests provided in the @testing-library/angular-app package, follow these steps:

    1. Clone or download the repository.
    2. Navigate to the repository root and install dependencies using npm install.
    3. Execute the example tests using the command npm run test:example-app.

    Note: The tests in this repository are configured to run with Vitest, but you are free to use a different test runner if preferred.

    npm install
npm run test:example-app

  8. Use patched queries and waitFor

    main

    The screen, within, waitFor, and waitForElementToBeRemoved utilities exported by @testing-library/angular are patched versions of the standard @testing-library/dom utilities.

    They are enhanced to automatically trigger Angular's change detection cycle (detectChanges()) before executing queries or callbacks. This ensures that your tests always see the most up-to-date DOM state without requiring manual fixture.detectChanges() calls in most scenarios.

    import { render, screen, waitFor } from '@testing-library/angular';

await render(MyComponent);

// waitFor automatically triggers change detection
await waitFor(() => {
  expect(screen.getByText('Loaded')).toBeInTheDocument();
});

  9. Understand the RenderResult object

    main

    When you call render, it returns a RenderResult object. This object provides access to the rendered DOM, Angular testing utilities, and helper methods to manipulate the component during tests.

    Key properties include:

    • container: The HTMLElement containing the rendered component.
    • debug(): Prints the component's DOM to the console with syntax highlighting.
    • detectChanges(): Manually triggers an Angular change detection cycle.
    • debugElement: The Angular DebugElement for the component.
    • fixture: The Angular ComponentFixture of the component or its wrapper.
    • navigate(): Navigates to a specific href or path.
    • rerender(): Re-renders the component with new properties.
    • renderDeferBlock(): Sets the state of a specific @defer block.
    // Example of using RenderResult properties
const { container, debug, detectChanges, fixture } = await render(AppComponent);

debug(container);
detectChanges();

  10. Install @testing-library/angular via ng add

    main

    You can install the library and its optional peer dependencies using the Angular CLI's ng add command. This schematic automatically adds @testing-library/dom as a dev dependency and can optionally include @testing-library/jest-dom and @testing-library/user-event based on the provided schema options.

    To use this schematic, run:

    ng add @testing-library/angular

    If you want to include the optional dependencies, you can pass them as flags (depending on how the schematic is published):

    ng add @testing-library/angular --install-jest-dom --install-user-event
    ng add @testing-library/angular

  11. Migrate to zoneless mode using the Angular schematic

    main

    The migrate-to-zoneless schematic automates the process of updating your test imports when moving to Angular's zoneless mode. It scans your TypeScript files for imports from @testing-library/angular and replaces them with imports from @testing-library/angular/zoneless.

    This schematic is intended to be run via the Angular CLI (schematics) to ensure all test files are updated consistently.