testing-library / jasmine-dom

🦥 Custom Jasmine matchers to test the state of the DOM

@testing-library/angular

Simple and complete Angular testing utilities that encourage good testing practices.

Read The Docs | Edit the docs

---

Table of Contents

• Table of Contents
• The problem
• This solution
• Example
• Installation
• Version compatibility
• Guiding Principles
• Contributors
• Docs
• FAQ
  • I am using Reactive Forms and the jest-dom matcher toHaveFormValues always returns an empty object or there are missing fields. Why?
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
  • ❓ Questions
• Getting started with GitHub Codespaces
• LICENSE

The problem

You want to write maintainable tests for your Angular components. As a part of this goal, you want your tests to avoid including implementation details of your components and rather focus on making your tests give you the confidence for which they are intended. As part of this, you want your testbase to be maintainable in the long run so refactors of your components (changes to implementation but not functionality) don't break your tests and slow you and your team down.

This solution

The @testing-library/angular is a very lightweight solution for testing Angular components. It provides light utility functions on top of Angular and @testing-library/dom, in a way that encourages better testing practices. Its primary guiding principle is:

The more your tests resemble the way your software is used, the more confidence they can give you.

Example

counter.component.ts

@Component({
  selector: 'app-counter',
  template: `
    <button (click)="decrement()">-</button>
    <span>Current Count: {{ counter }}</span>
    <button (click)="increment()">+</button>
  `,
})
export class CounterComponent {
  @Input() counter = 0;

  increment() {
    this.counter += 1;
  }

  decrement() {
    this.counter -= 1;
  }
}

counter.component.spec.ts

import { render, screen, fireEvent } from '@testing-library/angular';
import { CounterComponent } from './counter.component';

describe('Counter', () => {
  test('should render counter', async () => {
    await render(CounterComponent, { componentProperties: { counter: 5 } });

    expect(screen.getByText('Current Count: 5'));
  });

  test('should increment the counter on click', async () => {
    await render(CounterComponent, { componentProperties: { counter: 5 } });

    const incrementButton = screen.getByRole('button', { name: '+' });
    fireEvent.click(incrementButton);

    expect(screen.getByText('Current Count: 6'));
  });
});

See more examples

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's devDependencies:

npm install @testing-library/angular --save-dev

You may also be interested in installing jest-dom so you can use the custom jest matchers.

Docs

Version compatibility

Angular	Angular Testing Library
18.x	16.x, 15.x, 14.x, 13.x
17.x	16.x, 15.x, 14.x, 13.x
16.x	14.x, 13.x
>= 15.1	14.x, 13.x
< 15.1	12.x, 11.x
14.x	12.x, 11.x

Guiding Principles

The more your tests resemble the way your software is used, the more confidence they can give you.

We try to only expose methods and utilities that encourage you to write tests that closely resemble how your Angular components are used.

Utilities are included in this project based on the following guiding principles:

1. If it relates to rendering components, it deals with DOM nodes rather than component instances, nor should it encourage dealing with component instances.
2. It should be generally useful for testing individual Angular components or full Angular applications.
3. Utility implementations and APIs should be simple and flexible.

At the end of the day, what we want is for this library to be pretty light-weight, simple, and understandable.

Contributors

Thanks goes to these people (emoji key):

Tim Deschryver 💻 📖 🚇 ⚠️	Michaël De Boey 📖	Ignacio Le Fluk 💻 ⚠️	Tamás Szabó 💻	Gregor Woiwode 💻	Toni Villena 🐛 💻 📖 ⚠️	ShPelles 📖
Miluoshi 💻 ⚠️	Nick McCurdy 📖	Srinivasan Sekar 📖	Bitcollage 📖	Emil Sundin 💻	Ombrax 💻	Rafael Santana 💻 ⚠️ 🐛
Benjamin Blackwood 📖 ⚠️	Gustavo Porto 📖	Bo Vandersteene 💻	Janek 💻 ⚠️	Gleb Irovich 💻 ⚠️	Arjen 💻 🚧	Suguru Inatomi 💻 🤔
Amit Miran 🚇	Jan-Willem Willebrands 💻	Sandro 💻 🐛	Michael Westphal 💻 ⚠️	Lukas 💻	Matan Borenkraout 🚧	mleimer 📖 ⚠️
MeIr 🐛 ⚠️	John Dengis 💻 ⚠️	Rokas Brazdžionis 💻	Mateus Duraes 💻	Josh Joseph 💻 ⚠️	Torsten Knauf 🚧	antischematic 🐛 🤔
Florian Pabst 💻	Mark Goho 🚧 📖	Jan-Willem Baart 💻 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

Docs

Read The Docs | Edit the docs

FAQ

I am using Reactive Forms and the jest-dom matcher toHaveFormValues always returns an empty object or there are missing fields. Why?

Only form elements with a name attribute will have their values passed to toHaveFormsValues.

Issues

Looking to contribute? Look for the Good First Issue label.

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

See Bugs

💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

❓ Questions

For questions related to using the library, please visit a support community instead of filing an issue on GitHub.

• Discord
• Stack Overflow

Getting started with GitHub Codespaces

To get started, create a codespace for this repository by clicking this 👇

A codespace will open in a web-based version of Visual Studio Code. The dev container is fully configured with software needed for this project.

Note: Dev containers is an open spec which is supported by GitHub Codespaces and other tools.

LICENSE

MIT

jasmine-dom's Issues

Remove type defintions

We have currently @types/testing-library__jasmine-dom installed which make problematic upgrade type definitions. Since we want definitions of a version to yet to exist which means wrong definitions. There are 2 options:

1. Remove definitions package
2. Contain the actual TS definitions

I recommend the first option

Inverting matchers doesn't affect error message

• jasmine-dom version: 0.0.0-semantic

Relevant code or config:

expect(screen.getByText('Yes')).not.toBeChecked();

What you did:

Inverted a toBeChecked match - which failed.

What happened:

Error: FAILED Expected the element input type="radio" to be checked and it isn't checked.

What should have happened:

Message should either be:
Error: FAILED Expected the element input type="radio" not to be checked and it is.
Or:
Error: FAILED Expected the element input type="radio" checked value to match false but it was true

Missing dependency: dom-accessibility-api

• jasmine-dom version: 1.3.2
• node version: 14
• npm (or yarn) version: 6.14.17

Relevant code or config:

var your => (code) => here;

What you did:

What happened:

ERROR in ./node_modules/@testing-library/jasmine-dom/dist/toHaveAccessibleName.js 7:27-59
Module not found: Error: Can't resolve 'dom-accessibility-api'

Reproduction:

import JasmineDOM from '@testing-library/jasmine-dom';

Problem description:

Suggested solution:

add dom-accessibility-api to dependencies

Vulnerabilities

Hi, sorry about this, but I can't use my forked version of your library because it has 3 vulnerabilities and I can't seem to fix them?

found 3 vulnerabilities (2 moderate, 1 high) in 1464 scanned packages
  3 vulnerabilities require manual review. See the full report for details.

C:\src\jasmine-dom>npm audit fix
up to date in 8.942s

95 packages are looking for funding
  run `npm fund` for details

fixed 0 of 3 vulnerabilities in 1464 scanned packages
  3 vulnerabilities required manual review and could not be updated

I've tried updating kcd-scripts but it didn't make any difference?

Instructions do not work on Angular 10 CLI project

I have an Angular 10 CLI project (v10.1.2). I've installed @testing-library/[email protected], but as I'm using Karma (configured via Angular) and Typescript, I'm not sure how to install this library!

I tried following the instructions for the latest version (v1.1.0), but while I can see the matchers on the HTMLMatchers type in VSCode, I can't actually add the Matchers, because trying to import them with import JasmineDOM from '@testing-library/jasmine-dom'; gives an error File C:/.../node_modules/@types/testing-library__jasmine-dom/index.d.ts is not a module.

As this is an Angular CLI project, would it actually make more sense to use a karma plugin!?

Could not find a declaration file for module '@testing-library/jasmine-dom/dist' on Angular 12 project

• jasmine-dom version: 1.0.3
• node version: 14.15.4
• npm version: 6.14.10
• @angular/core version: 12.2.9
• typescript version: 4.3.2
• jasmine-core version: 3.8.0

Relevant code or config:

tsconfig.spec.json:

/* To learn more about this file see: https://angular.io/config/tsconfig. */
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "types": ["jasmine", "@testing-library/jasmine-dom"]
  },
  "files": ["src/test.ts", "src/polyfills.ts"],
  "include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
}

test.ts:

// This file is required by karma.conf.js and loads recursively all the .spec and framework files

import 'zone.js/testing';
import { getTestBed } from '@angular/core/testing';
import {
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting,
} from '@angular/platform-browser-dynamic/testing';

import JasmineDOM from '@testing-library/jasmine-dom/dist';

declare const require: {
  context(
    path: string,
    deep?: boolean,
    filter?: RegExp
  ): {
    keys(): string[];
    <T>(id: string): T;
  };
};

// First, initialize the Angular testing environment.
getTestBed().initTestEnvironment(BrowserDynamicTestingModule, platformBrowserDynamicTesting());
// Then we find all the tests.
const context = require.context('./', true, /\.spec\.ts$/);
// And load the modules.
context.keys().map(context);

beforeAll(() => {
  // On the Jasmine version I'm using the addMatches method is directly on the jasmine variable instead of having to call .getEnv()
  jasmine.addMatchers(JasmineDOM);
});

What you did:

Tried to run the tests:

npm run-script test

After the error happened, installed the types package as suggested in the error message, but the same error occurred:

npm run-script testnpm i --save-dev @types/testing-library__jasmine-dom

What happened:

Error: src/test.ts:10:24 - error TS7016: Could not find a declaration file for module '@testing-library/jasmine-dom/dist'. 'C:/some-path/angular/node_modules/@testing-library
/jasmine-dom/dist/index.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/testing-library__jasmine-dom` if it exists or add a new declaration (.d.ts) file containing `declare module '@testing-library/jasmine-dom/dist';`

10 import JasmineDOM from '@testing-library/jasmine-dom/dist';

Problem description:

I couldn't make it work on an Angular 12 project by following the TypeScript instructions on the README file.
Please note that on tests.ts I had to call jasmine.addMatchers(JasmineDOM); without .getEnv() as it was suggested in the README. Anyway the error happens before this line.

I also took a look at this other related issue, but couldn't find anything that could solve this.

Is there any additional configuration I need to make this work?
Thanks in advance for the support and for providing this helpful library!