A little helper to unit test React components in the open source Cypress.io test runner v7.0.0+
Jump to: Comparison, Blog posts, Install, Examples: basic, advanced, full, external, Style options, Code coverage, Visual testing, Common problems, Chat
TLDR
- What is this? This package allows you to use Cypress test runner to unit test your Angular components with zero effort. Here is a typical component testing, notice there is not external URL shown, since it is mounting the component directly.
- How is this different from Angular Testing or ATL? It is similar in functionality BUT runs the component in the real browser with full power of Cypress E2E test runner: live GUI, full API, screen recording, CI support, cross-platform, and visual testing.
- Read My Vision for Component Tests in Cypress by Gleb Bahmutov
Comparison
| Feature | Jest / Karma / ATL | Cypress + @cypress/angular |
|---|---|---|
| Test runs in real browser | ❌ | ✅ |
| Supports shallow mount | ✅ | ❌ |
| Supports full mount | ✅ | ✅ |
| Test speed | 🏎 | as fast as the app works in the browser |
| Test can use additional plugins | maybe | use any Cypress plugin |
| Test can interact with component | synthetic limited API | use any Cypress command |
| Test can be debugged | via terminal and Node debugger | use browser DevTools |
| Built-in time traveling debugger | ❌ | Cypress time traveling debugger |
| Re-run tests on file or test change | ✅ | ✅ |
| Test output on CI | terminal | terminal, screenshots, videos |
| Tests can be run in parallel | ✅ | ✅ via parallelization |
| Test against interface | if using @testing-library/angular |
✅ and can use @testing-library/cypress |
| Spying and stubbing methods | Jest mocks | Sinon library |
| Stubbing imports | ✅ | ✅ |
| Stubbing clock | ✅ | ✅ |
| Code coverage | ✅ | ✅ |
If you are coming from Jest + ATL world, read Test The Interface Not The Implementation.
Blog posts
Install
Requires Node version 12 or above.
npm install --save-dev cypress @cypress/angular @cypress/webpack-dev-server
API
mountallows you to mount a given Angular component as a mini web application and interact with it using Cypress commands
Examples
import { mount } from '@cypress/angular'
import { HelloWorldComponent } from './hello-world.component'
describe('HelloWorldComponent', () => {
it('works', () => {
mount(HelloWorldComponent)
// now use standard Cypress commands
cy.contains('Hello World!').should('be.visible')
})
})
Look at the examples in cypress/component folder. Here is the list of examples showing various testing scenarios.
Basic examples
Coming Soon...
Advanced examples
Coming Soon...
Full examples
Coming Soon...
External examples
Coming Soon...
Options
Code coverage
In order to use code coverage you can follow the instructions from docs. In most of cases you need to install 2 dependencies:
npm i @cypress/code-coverage babel-plugin-istanbul
yarn add @cypress/code-coverage babel-plugin-istanbul
If you are using plugins/cra-v3 it instruments the code on the fly using babel-plugin-istanbul and generates report using dependency cypress-io/code-coverage (included). If you want to disable code coverage instrumentation and reporting, use --env coverage=false or CYPRESS_coverage=false or set in your cypress.json file
{
"env": {
"coverage": false
}
}
Visual testing
You can use any Cypress Visual Testing plugin to perform visual testing from the component tests. This repo has several example projects, see visual-sudoku, visual-testing-with-percy, visual-testing-with-happo, and visual-testing-with-applitools.
For a larger Do-It-Yourself example with an hour long list of explanation videos, see bahmutov/sudoku repository. I explain how to write visual testing using open source tools in this blog post, video talk, and slides.
Common problems
Chat
Come chat with us on discord in the #component-testing channel.
Development
Debugging
You can see verbose logs from this plugin by running with environment variable
DEBUG=@cypress/angular
Because finding and modifying Webpack settings while running this plugin is done by find-webpack module, you might want to enable its debug messages too.
DEBUG=@cypress/angular,find-webpack
Changelog
Related tools
Same feature for unit testing components from other frameworks using Cypress