Skip to content

Commit 21a03cb

Browse files
jordanpowell88jordanpowell88
committed
feat(angular): create mount lib
1 parent fdf52cb commit 21a03cb

File tree

18 files changed

+866
-13
lines changed

18 files changed

+866
-13
lines changed

‎cli/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ vue
1919
vue2
2020
react
2121
mount-utils
22+
angular

‎cli/angular/CHANGELOG.md‎

Whitespace-only changes.

‎cli/angular/README.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
> A little helper to unit test React components in the open source [Cypress.io](https://www.cypress.io/) test runner **v7.0.0+**
2+
3+
**Jump to:** [Comparison](#comparison), [Blog posts](#blog-posts), [Install](#install), Examples: [basic](#basic-examples), [advanced](#advanced-examples), [full](#full-examples), [external](#external-examples), [Style options](#options), [Code coverage](#code-coverage), [Visual testing](#visual-testing), [Common problems](#common-problems), [Chat](#chat)
4+
5+
## TLDR
6+
7+
- What is this? This package allows you to use [Cypress](https://www.cypress.io/) 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.
8+
9+
![Example component test](images/dynamic.gif)
10+
11+
- How is this different from [Angular Testing](https://angular.io/guide/testing) or [ATL](https://testing-library.com/docs/angular-testing-library/intro/)? 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](https://www.cypress.io/features/), and [visual testing](https://on.cypress.io/visual-testing).
12+
- Read [My Vision for Component Tests in Cypress](https://glebbahmutov.com/blog/my-vision-for-component-tests/) by Gleb Bahmutov
13+
14+
## Comparison
15+
16+
<!-- prettier-ignore-start -->
17+
Feature | Jest / Karma / ATL | Cypress + `@cypress/angular`
18+
--- | --- | ---
19+
Test runs in real browser | ❌ | ✅
20+
Supports shallow mount | ✅ | ❌
21+
Supports full mount | ✅ | ✅
22+
Test speed | 🏎 | [as fast as the app works in the browser](#fast-enough)
23+
Test can use additional plugins | maybe | use any [Cypress plugin](https://on.cypress.io/plugins)
24+
Test can interact with component | synthetic limited API | use any [Cypress command](https://on.cypress.io/api)
25+
Test can be debugged | via terminal and Node debugger | use browser DevTools
26+
Built-in time traveling debugger | ❌ | Cypress time traveling debugger
27+
Re-run tests on file or test change | ✅ | ✅
28+
Test output on CI | terminal | terminal, screenshots, videos
29+
Tests can be run in parallel | ✅ | ✅ via [parallelization](https://on.cypress.io/parallelization)
30+
Test against interface | if using `@testing-library/angular` | ✅ and can use `@testing-library/cypress`
31+
Spying and stubbing methods | Jest mocks | [Sinon library](https://on.cypress.io/stubs-spies-and-clocks)
32+
Stubbing imports | ✅ | ✅
33+
Stubbing clock | ✅ | ✅
34+
Code coverage | ✅ | ✅
35+
<!-- prettier-ignore-end -->
36+
37+
If you are coming from Jest + ATL world, read [Test The Interface Not The Implementation](https://glebbahmutov.com/blog/test-the-interface/).
38+
39+
## Blog posts
40+
41+
- [My Vision for Component Tests in Cypress](https://glebbahmutov.com/blog/my-vision-for-component-tests/)
42+
43+
## Install
44+
45+
Requires [Node](https://nodejs.org/en/) version 12 or above.
46+
47+
```sh
48+
npm install --save-dev cypress @cypress/angular @cypress/webpack-dev-server
49+
```
50+
51+
52+
## API
53+
54+
- `mount` allows you to mount a given Angular component as a mini web application and interact with it using Cypress commands
55+
56+
## Examples
57+
58+
```ts
59+
import { mount } from '@cypress/angular'
60+
import { HelloWorldComponent } from './hello-world.component'
61+
62+
describe('HelloWorldComponent', () => {
63+
it('works', () => {
64+
mount(HelloWorldComponent)
65+
// now use standard Cypress commands
66+
cy.contains('Hello World!').should('be.visible')
67+
})
68+
})
69+
```
70+
71+
Look at the examples in [cypress/component](cypress/component) folder. Here is the list of examples showing various testing scenarios.
72+
73+
### Basic examples
74+
Coming Soon...
75+
76+
77+
### Advanced examples
78+
Coming Soon...
79+
80+
### Full examples
81+
Coming Soon...
82+
83+
### External examples
84+
Coming Soon...
85+
86+
## Options
87+
88+
89+
## Code coverage
90+
91+
In order to use code coverage you can follow the instructions from [docs](https://github.com/cypress-io/code-coverage). In most of cases you need to install 2 dependencies:
92+
93+
```
94+
npm i @cypress/code-coverage babel-plugin-istanbul
95+
96+
yarn add @cypress/code-coverage babel-plugin-istanbul
97+
```
98+
99+
If you are using [plugins/cra-v3](plugins/cra-v3) it instruments the code on the fly using `babel-plugin-istanbul` and generates report using dependency [cypress-io/code-coverage](https://github.com/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
100+
101+
```json
102+
{
103+
"env": {
104+
"coverage": false
105+
}
106+
}
107+
```
108+
109+
## Visual testing
110+
111+
You can use any Cypress [Visual Testing plugin](https://on.cypress.io/plugins#visual-testing) to perform [visual testing](https://on.cypress.io/visual-testing) from the component tests. This repo has several example projects, see [visual-sudoku](examples/visual-sudoku), [visual-testing-with-percy](examples/visual-testing-with-percy), [visual-testing-with-happo](examples/visual-testing-with-happo), and [visual-testing-with-applitools](examples/visual-testing-with-applitools).
112+
113+
For a larger Do-It-Yourself example with an hour long list of explanation videos, see [bahmutov/sudoku](https://github.com/bahmutov/sudoku) repository. I explain how to write visual testing using open source tools in this [blog post](https://glebbahmutov.com/blog/open-source-visual-testing-of-components/), [video talk](https://www.youtube.com/watch?v=00BNExlJUU8), and [slides](https://slides.com/bahmutov/i-see-what-is-going-on).
114+
115+
## Common problems
116+
117+
118+
## Chat
119+
120+
Come chat with us [on discord](https://discord.gg/7ZHYhZSW) in the #component-testing channel.
121+
122+
## Development
123+
124+
See [docs/development.md](./docs/development.md)
125+
126+
## Debugging
127+
128+
You can see verbose logs from this plugin by running with environment variable
129+
130+
```
131+
DEBUG=@cypress/angular
132+
```
133+
134+
Because finding and modifying Webpack settings while running this plugin is done by [find-webpack](https://github.com/bahmutov/find-webpack) module, you might want to enable its debug messages too.
135+
136+
```
137+
DEBUG=@cypress/angular,find-webpack
138+
```
139+
140+
## Changelog
141+
142+
[Changelog](./CHANGELOG.md)
143+
144+
## Related tools
145+
146+
Same feature for unit testing components from other frameworks using Cypress
147+
148+
- [@cypress/react](https://github.com/cypress-io/cypress/tree/develop/npm/react)
149+
- [@cypress/vue](https://github.com/cypress-io/cypress/tree/develop/npm/vue)
150+
- [cypress-cycle-unit-test](https://github.com/bahmutov/cypress-cycle-unit-test)
151+
- [cypress-svelte-unit-test](https://github.com/bahmutov/cypress-svelte-unit-test)
152+
- [@cypress/angular](https://github.com/bahmutov/@cypress/angular)
153+
- [cypress-hyperapp-unit-test](https://github.com/bahmutov/cypress-hyperapp-unit-test)
154+
- [cypress-angularjs-unit-test](https://github.com/bahmutov/cypress-angularjs-unit-test)

‎cli/angular/package.json‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{
2+
"name": "@cypress/angular",
3+
"version": "0.0.0-development",
4+
"description": "Test Angular Components using Cypress",
5+
"main": "dist/cypress-angular.esm-bundler.js",
6+
"scripts": {
7+
"build": "rimraf dist && rollup -c rollup.config.js",
8+
"postbuild": "node ../../scripts/sync-exported-npm-with-cli.js",
9+
"build-prod": "yarn build",
10+
"cy:open": "node --inspect-brk ../../scripts/start.js --component-testing --run-project ${PWD}",
11+
"cy:run": "node ../../scripts/cypress.js run --component",
12+
"cy:run:debug": "node --inspect-brk ../../scripts/start.js --component-testing --run-project ${PWD}",
13+
"test": "yarn cy:run",
14+
"watch": "yarn build --watch --watch.exclude ./dist/**/*"
15+
},
16+
"dependencies": {},
17+
"devDependencies": {
18+
"@angular/common": "^14.0.6",
19+
"@angular/core": "^14.0.6",
20+
"@angular/platform-browser-dynamic": "^14.0.6",
21+
"@rollup/plugin-node-resolve": "^11.1.1",
22+
"rollup-plugin-typescript2": "^0.29.0",
23+
"typescript": "^4.2.3"
24+
},
25+
"peerDependencies": {
26+
"@angular/common": ">=13",
27+
"@angular/core": ">=13",
28+
"@angular/platform-browser-dynamic": ">=13"
29+
},
30+
"files": [
31+
"dist"
32+
],
33+
"types": "dist/index.d.ts",
34+
"license": "MIT",
35+
"repository": {
36+
"type": "git",
37+
"url": "https://github.com/cypress-io/cypress.git"
38+
},
39+
"homepage": "https://github.com/cypress-io/cypress/blob/master/npm/angular/#readme",
40+
"author": "Jordan Powell",
41+
"bugs": "https://github.com/cypress-io/cypress/issues/new?assignees=&labels=npm%3A%20%40cypress%2Fangular&template=1-bug-report.md&title=",
42+
"keywords": [
43+
"angular",
44+
"cypress",
45+
"cypress-io",
46+
"test",
47+
"testing"
48+
],
49+
"contributors": [
50+
{
51+
"name": "Jordan Powell",
52+
"social": "@jordanpowell88"
53+
},
54+
{
55+
"name": "Zach Williams",
56+
"social": "@ZachJW34"
57+
}
58+
],
59+
"module": "dist/cypress-angular.esm-bundler.js",
60+
"publishConfig": {
61+
"access": "public"
62+
},
63+
"standard": {
64+
"globals": [
65+
"Cypress",
66+
"cy",
67+
"expect"
68+
]
69+
}
70+
}

‎cli/package.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,8 @@
107107
"mount-utils",
108108
"vue",
109109
"react",
110-
"vue2"
110+
"vue2",
111+
"angular"
111112
],
112113
"bin": {
113114
"cypress": "bin/cypress"
@@ -144,6 +145,11 @@
144145
"./mount-utils": {
145146
"require": "./mount-utils/dist/index.js",
146147
"types": "./mount-utils/dist/index.d.ts"
148+
},
149+
"./angular": {
150+
"import": "./angular/dist/cypress-angular.esm-bundler.js",
151+
"require": "./angular/dist/cypress-angular.esm-bundler.js",
152+
"types": "./angular/dist/index.d.ts"
147153
}
148154
},
149155
"workspaces": {

‎npm/angular/.eslintrc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"plugins": [
3+
"cypress"
4+
],
5+
"extends": [
6+
"plugin:@cypress/dev/tests"
7+
],
8+
"env": {
9+
"cypress/globals": true
10+
},
11+
"rules": {
12+
"mocha/no-global-tests": "off",
13+
"no-unused-vars": "off",
14+
"no-console": "off",
15+
"@typescript-eslint/no-unused-vars": "off"
16+
}
17+
}

‎npm/angular/.npmignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
examples
2+
src
3+
cypress

‎npm/angular/.releaserc.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
module.exports = {
2+
...require('../../.releaserc.base'),
3+
branches: [
4+
{ name: 'master', channel: 'latest' },
5+
],
6+
}

‎npm/angular/CHANGELOG.md‎

Whitespace-only changes.

0 commit comments

Comments
 (0)