DEV Community: David Würfel

CI ready e2e tests for Angular with Cypress and TypeScript in under 60 minutes

David Würfel — Mon, 23 Mar 2020 07:05:37 +0000

This article aims to describe how you can set up end-to-end testing for Angular with Cypress including TypeScript. You will write your very first e2e tests and make them ready to run on a CircleCI as a continuous integration system with every update to your repository.

Before we start: What is an e2e test?

End-to-end (short e2e) testing is a type of software testing that validates the software system along with its integration with external interfaces. The purpose of end-to-end test is to exercise a complete production-like scenario.

Source: https://www.guru99.com/end-to-end-testing.html.

Overview

What is Cypress?
Prerequisites
Setting up Cypress
Writing Some Tests
Setting up Continuous Integration
Conclusion and References

I have a frontend development background in Microsoft's .NET & WPF and remember the times where we evaluated costly frameworks to write end-to-end tests for our projects. After a lot of evaluations and weeks, even months of custom glue code and development of test infrastructures on top of existing tools, we finally got some e2e tests running. They were brittle, often failed because of manual adjustments we had to do or problems with flaky runners in the continuous integration pipeline.

Some years later with Angular and Protractor as a default for e2e tests, we were still based on page objects, Selenium Web Driver and the tests continued to be rather unreliable. No expensive commercial frameworks and custom infrastructure were needed. But was it fun to write e2e tests? No.

However we are in 2020 now and time has come for new heroes to arise. 🚀

What is Cypress?

Cypress promises fast, easy and reliable testing for anything that runs in a browser. It is not based on Selenium Web Driver which is using network connections to interact with your browser. Instead Cypress is a test runner that runs inside your browser next to your web application and therefore has has direct control over it.

Without going into all the details, this not only makes Cypress faster and more reliable, it also opens the door for a lot of other interesting features like

time travel debugging,
easy snapshotting and recording,
automatic waitings.

On top of all the features, Cypress has a developer experience (DX) that is nearly unrivalled. Have you ever seen a message in the error logs of your failed build that tells you exactly what you did wrong, points you to the right dependencies to add and also links to an explanatory documentation site describing the problem? This is what Cypress feels like. It is built by developers for developers.

Hereafter, we will install Cypress for a fresh Angular project created with the CLI. We'll write some e2e tests and conclude with running these by an automated build system. All these steps should not take more than 60 minutes. We try to keep the steps as short as possible, leveraging existing tools like Angular Schematics, libraries and common templates.

Prerequisites

This guide assumes that you have a standard Angular 9 app project. If not, you may create one like you would normally do with the Angular CLI. If you don't have the CLI installed globally, you can make use of the npx command that will install it temporarily on the fly:

npx @angular/cli new <app-name>

Setting up Cypress

In order to set up Cypress together with TypeScript as fast as possible, we make use of an existing schematic developed by BrieBug.

In the root of your Angular project, you can open the terminal and enter the following command:

ng add @briebug/cypress-schematic --addCypressTestScripts

If the CLI isn't installed globally, the ng command may not be available directly. You can enforce the use of the local ng from the package.json:

npm run ng -- add @briebug/cypress-schematic # In case 'ng' could not be found

We can safely remove Protractor because it will be completely replaced. During the installation some binaries were downloaded because Cypress comes with an Electron-bundled UI as an interactive test runner.

Using the flag --addCypressTestScripts two handy npm scripts were added to make the work with Cypress more comfortable. One to run e2e tests headless and the other script running the tests with the Cypress UI runner:

    // package.json scripts

    "cy:run": "cypress run",
    "cy:open": "cypress open"

If you were to run one of these scripts standalone, the test would fail because it tries to route to http://localhost:4200 where nothing is served at the moment. In order to fix this, we need to open a second terminal and serve our Angular application beforehand with npm start.

Luckily the schematic adjusted the e2e command so that this is done for you automatically by the CLI builder. You can serve the application and start the e2e test by using the following command:

npm run e2e

Cypress will detect that we launched it for the first time. It verifies its installation and adds some initial example files. After the UI has opened up, we can see a test that has already been created for us.

Selecting the test will run it. Initially the test will fail because we didn't actually test something properly. We will fix this now.

Writing Some Tests

As a very first step, as proposed by the Cypress best practices, we set our global baseUrl, so that we don't have to duplicate this on every test execution. Add the following to the configuration cypress.json:

// cypress.json
{
  "baseUrl": "http://localhost:4200"
}

After that, we write our very first smoke test that only checks whether the default app title is set on the Angular starting page. Therefore, change the content of the spec.ts to the following content:

// spec.ts
it('smoke test', () => {
  cy.visit('/');
  cy.contains('cypress-e2e-testing-angular app is running!');
});

The test starts by routing to our baseUrl and proceeds by querying any element that contains the text cypress-e2e-testing-angular app is running!.

Testing User Flows

This test should already work, but let's write some more interactive ones. As e2e are inherently slower than unit tests, it is totally fine to have e2e tests that model the entire user flow for a feature.

For example, we want to check whether some characteristics of the starting page are valid: Our page should contain the title and the ng generate text in the terminal by default, but when the users clicks the Angular Material button, we want to ensure that the proper ng add command is displayed in the terminal view below.

You may replace the content of your test file with this:

// spec.ts
describe('When Angular starting page is loaded', () => {
  beforeEach(() => {
    cy.visit('/');
  });

  it('has app title, shows proper command by default and reacts on command changes', () => {
    cy.contains('cypress-e2e-testing-angular');

    cy.contains('.terminal', 'ng generate component xyz');

    cy.contains('Angular Material').click();
    cy.contains('.terminal', 'ng add @angular/material');
  });
});

We refactored our test suite by adding a describe block to capture all tests that run when the starting page is loaded. As we visit the baseUrl every time, we moved this into the beforeEach call. Lastly we combined the basic smoke tests with the test for the terminal view on the starting page.

It is important to know that you should not store Cypress' query results in variables, but instead work with closures. Moreover, we selected elements by CSS classes and text content, which may be too brittle. It is recommended to use data- attributes for selecting elements.

Cypress has a lot of great features and possibilities. We won't cover all of them because our goal is to focus on the very first starting point. The official documentation is really good and covers everything on how to interact with elements.

If you rerun this test suite, you should see the UI clicking through each scenario and all three tests should pass this time. ✔✔✔

Setting up Continuous Integration

Now that our tests run locally, let's kick of a small CI (continuous integration) pipeline. A good way to prepare for this, is to create npm scripts and combine them so that the build system can use a single script as entry point. By following this method, you can try the CI steps locally before pushing online. Moreover npm scripts are rather independent from any actual build system.

On CI, we need to start our server in the background and wait for it to bundle our application, which might take a while. Then we need to start the Cypress test runner, go through the tests and shut down the server when the tests finish. Luckily we can do this all with a single utility called start-server-and-test as described in the Cypress docs:

npm install --save-dev start-server-and-test

After this is installed, we use the Angular serve which is currently behind npm start and combine it with the headless cy:run command:

   // package.json scripts
  "start": "ng serve",
  "cy:run": "cypress run",
  "e2e:ci": "start-server-and-test start http://localhost:4200 cy:run"

You could surely use a production build or build beforehand and serve the app using any http server. For sake of conciseness, I will leave these improvements up for you.

Circle CI

For our example, we choose CircleCI because it integrates very well with GitHub, is commonly used there and has a free plan. You may use any other CI system like Jenkins or GitLab (which I have the most experience with). After signing into CircleCI and connecting to our GitHub account, you can select the repository and create a new project via their dashboard.

In order to configure the pipeline, you could write a config.yml by selecting a template and adjusting it to your needs and eventually running the e2e script. Fortunately Cypress has a ready to use configurations (called Orbs) for CircleCI which already include the installation of dependencies, caching and so on. Before we can use it, we must visit the Organisation Settings to enable third party runners.

# circleci/config.yml

version: 2.1
orbs:
  # This Orb includes the following:
  # - checkout current repository
  # - npm install with caching
  # - start the server
  # - wait for the server to respond
  # - run Cypress tests
  # - store videos and screenshots as artifacts on CircleCI
  cypress: cypress-io/cypress@1
workflows:
  build:
    jobs:
      - cypress/run:
          start: npm start
          wait-on: 'http://localhost:4200'
          store_artifacts: true

The pipeline only has one job: Run all e2e tests. It checks out the current branch, installs all dependencies including caching, starts the application server and runs our tests. Additionally, videos (recorded by default) and screenshots (in case tests are failing) are uploaded as CircleCI artifacts for further inspection.*

Conclusion

The steps in this guide are rather minimal. You may use your existing Angular project, may change the configuration of your Cypress test suites and write a lot of more meaningful tests. Moreover, you may define npm scripts for different scenarios and environments and of course your entire build pipeline may be extended with linting, unit testing, building and even deploying your application. Nevertheless, this should be a first step which shows how quick automated end-to-end tests can be set up in nowadays.

Wait till you write real Cypress tests for your application. You will have fun!

I hope that you will also find some value in this article. If you have any questions or remarks, just let me know. Your feedback is very welcome!

You can find the sources for this guide on GitHub:

MrCube42 / cypress-e2e-testing-angular

Example Angular 9 app using Cypress for end-to-end testing.

CypressE2eTestingAngular

This project was generated with Angular CLI version 9.0.6.

Development server

Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

Code scaffolding

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory. Use the --prod flag for a production build.

Running unit tests

Run ng test to execute the unit tests via Karma.

Running end-to-end tests

Run npm run e2e to execute the end-to-end tests via Cypress.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.

View on GitHub

References

*For other CI systems we could use our previously defined npm script. However we need to take care of all the additional work by ourselves. If you already have an existing sophisticated pipeline it could be easier to integrate just the script.

Setup Jest for Angular with Debugging in Visual Studio Code

David Würfel — Mon, 09 Dec 2019 19:31:41 +0000

This article aims to describe a really fast step-by-step way to setup Jest testing for Angular projects including debugging capabilities of Visual Studio Code.

Overview

Why Jest?
Prerequisites
Removal of Karma (and Jasmine)
Setting up Jest
Configure Debugging in VS Code
Outlook and References

I always thought that no one will ever read my blog posts. However, I myself will surely read my own as long as I haven't completely automated the following steps. The upcoming information is already present online but varies and is distributed over several sources*. My goal is to describe everything that is needed in one single post.

Why Jest?

The default test runner for Angular applications is Karma in combination with Jasmine as test framework. In recent times I often prefer Jest as testing framework. In my opinion it has some advantages over the default setup: It is headless out-of-the-box, less configuration is needed and it has some handy features like snapshot testing. Since Jest is headless which means that it won't spawn a browser window where you can open Chrome Dev Tools, it can get cumbersome to use console-logs when trying to debug while testing. The debug logs would spam the terminal and you will probably have to scroll a lot to find the outputs you are looking for. At this point you should think about using the great debugging features of your editor.

Some Prerequisites

This guide assumes that you are using Angular in version 8 (as it uses the new CLI builders). Moreover, I assume that we won't use Protractor as E2E testing framework. We're already living in heaven and may be using Cypress later. Therefore, we can safely remove anything related to Jasmine.

If you don't have an Angular application already, you may create one like you would normally do with the Angular CLI:

ng new <app-name>

The Cleanup

When it comes to source code or configuration, I am a huge friend of less is more. Any code snippet or configuration that is not needed or commented out can be removed. Our plan is to remove any Karma and Jasmine related dependencies and entities to always have a clean project.

Remove Protractor and Jasmine (Optional)

If you really want to use Protractor for your end-to-end tests you can skip this part. Otherwise, we will remove everything related to the E2E tests. If we have done this, we can remove everything related to Jasmine, too.

Remove the following because we won't use it anymore:

/e2e folder containing all your end-to-end tests and configuration
e2e section from angular.json
e2e entry in the README.md
e2e command from the scripts in the package.json

Now we can safely uninstall Protractor and Jasmine dependencies:

npm uninstall protractor
npm uninstall jasmine-core jasmine-spec-reporter @types/jasmine @types/jasminewd2

Remove Karma

Since we will use Jest for our entire testing we can now remove everything that is related to Karma.

Uninstall Karma dependencies:

npm uninstall karma karma-chrome-launcher karma-coverage-istanbul-reporter
karma-jasmine karma-jasmine-html-reporter

As we don't use Karma, we can remove the following files:

karma.conf.js
src/test.ts

The Setup

We cleaned up our project from any unused resources and will now setup our toolchain to run unit tests with Jest.

Add Jest

We can start by installing Jest, it's types and new Angular builder that is used to run the Jest tests:

npm install --save-dev jest @types/jest @angular-builders/jest

Adjust Angular CLI Configuration

Replace the previous Karma builder in the test section of the angular.json with the new Jest builder:

"test": {
  "builder": "@angular-builders/jest:run",
  "options": { 
    // The options and everything in here can be removed.
  }

Adjust TypeScript Configurations

In your configuration for the tests (tsconfig.spec.json) change the entry jasmine in the types array to jest and remove the file src/test.ts from the files array. Set emitDecoratorMetadata and esModuleInterop to true. The first one is needed for Angular's dependency injection to work this Jest, the latter one is suggested by a Jest warning when running your tests.

{
  // ...
  {
    // ...
    "types": [
      "jest",
      "node"
    ],
    "emitDecoratorMetadata": true,
    "esModuleInterop": true
  },
  "files": ["src/polyfills.ts"]
  // ...
}

Lastly in your main base configuration tsconfig.json also change the types entry from jasmine to jest.

Add Minimal Jest Configuration (Optional)

When running Jest it complains that it cannot find a configuration file. Since I don't like such warnings we take this opportunity to add a minimal configuration that also setups up the code coverage format. I want the coverage to output a nice HTML site as an overview. You can use one of the Istanbul reporters here.

You can create the file jest.config.js in the root of your project and add the following contents:

module.exports = {
  coverageReporters: ['html', 'text', 'text-summary']
};

Adjust NPM Test Scripts (Optional)

I like to define two npm scripts to run my tests. The test script runs all tests and produces the code coverage. The test:watch script doesn't produce code coverage but watches for file changes (using the integrated Jest watch mode).

You can add the following to your package.json:

"scripts": {
  // ...
  "test": "ng test --coverage",
  "test:watch": "ng test --watch",
  // ...
}

Configure Debugging in VS Code

As debugging via console-logs can be tedious, especially when your unit tests are running in headless mode, we want to use the great debugging features of Visual Studio Code. The goal is to have two launch scripts to run and debug all tests and only tests that belong to the currently opened file.

If you press F5 or switch to the Debug view in VS Code you will start one of these launch scripts. They are located in the file .vscode/launch.json. You may add as many scripts as you want.

If not already present, create the file .vscode/launch.json and add the following two launch configurations to this file:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Jest All",
      "program": "${workspaceFolder}/node_modules/@angular/cli/bin/ng",
      "cwd": "${workspaceFolder}",
      "args": [
        "test",
        "--testMatch=\"**/+(*.)+(spec|test).+(ts|js)?(x)\"",
        "--runInBand"
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "disableOptimisticBPs": true,
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Jest Current File",
      "program": "${workspaceFolder}/node_modules/@angular/cli/bin/ng",
      "cwd": "${workspaceFolder}",
      "args": [
        "test",
        "--testMatch=\"**/+(*.)+(spec|test).+(ts|js)?(x)\"",
        "--testPathPattern=${fileBasenameNoExtension}",
        "--runInBand",
      ],
      "console": "integratedTerminal",
      "internalConsoleOptions": "neverOpen",
      "disableOptimisticBPs": true,
    }
  ]
}

The first script Jest All will run all tests. The second one Jest Current File will run all specs with a path that matches the filename (without extension) of your currently opened file. This means if you have opened either app.component.ts or app.component.spec.ts it will run the test app.component.spec.ts because both app.component and app.component.spec match the path of your spec. Smart, isn't it? 😉

You can now set breakpoints in your specs or components that will be hit upon running these scripts. It gives you the ability to use the entire toolchain of Visual Studio Code's debugging features. You don't need to console-log all your variables, you can inspect them right inside your editor while stepping through the program execution. 🤯

(Un)known Issues

It really had some trouble with the launch configurations. Sometimes it worked. Most times it causes Jest not to find any tests. After about half a day of searching, debugging and trying out different parameters, I found out that this is caused by the default testMatch parameter. It appears that VS Code uses the workspaceFolder and injects it into the parameter. However, it appears that the underlying Regex is not evaluated.

The solution was to explicitly set the current working directory ("cwd": "${workspaceFolder}") and overwriting the default testMatch parameter while removing the absolute path that VS Code injects itself ("--testMatch=\"**/+(*.)+(spec|test).+(ts|js)?(x)\"").

Bright Future

As mentioned in the beginning, I will probably look up my own blog post several times. At some point in future and if I have some spare time, I want to create my own Angular Schematic to ng new an Angular project and automate these initial steps. The schematic may then basically do the following:

ng new with parameter --minimal to prevent installing of any Karma or Jasmine related dependencies and files
Remove E2E mentions from the README and npm scripts for now (because they will still be added)
Add Jest dependencies
Add tsconfig.spec.json and adjust the tsconfig.json
Add test section to angular.json
Add jest.config.js
Add test and test:watch npm scripts
Add launch.json

I hope that you will also find some value in this article. If you have any questions or remarks, just let me know. Your feedback is very welcome!

You can find the sources for this guide on GitHub:

MrCube42 / angular-jest-vscode-debugging

Setup Jest for Angular with debugging in Visual Studio Code.

References

*There are schematics like the one from Briebug that add Jest with a single command. However, it does some things a bit different, I wanted to describe the steps to take without a schematic first and wanted to reduce the pain of setup debugging in VS Code.