Setting up End-to-End Testing in Angular Project with CodeceptJS

Angular comes with Protractor for end-to-end (E2E) testing. While Protractor works really nicely with Angular, it can be a bit tricky for non-technical team members to understand what the tests do. Writing the tests themselves can be too verbose.

CodeceptJS is a E2e testing framework which provides higher level APIs than Protractor. It provides “scenario-driven” or behavior-driven style APIs which is easier to understand and also to write tests for a feature/scenario. CodeceptJS has been a framework of choice for our team when it comes to E2E testing for Angular projects.

In this post, we will create a new Angular project using Angular CLI, then we will add CodeceptJS to the project and use CodeceptJS for E2E testing.

This article is based on Angular CLI version 1.5.5, Angular framework version 5.0.5, and CodeceptJS version 1.0.3.
A companion git repo for this post is on GitHub at armno/angular-e2e-codeceptjs-example.

Update 2017–12–18: CodeceptJS released version 1.1 which has Puppeteer helper built in. This means Selenium + WebDriver are no longer required.

1. Create a new Angular project with Angular CLI

$ ng new <project name>

Here we use $ ng new command to create a new Angular project. Then we can run e2e tests using $ ng e2e command.

2. Install CodeceptJS

The official guide suggests installing CodeceptJS globally.

$ npm install -g codeceptjs

However, I prefer having everything inside the project so I install it locally instead.

$ npm install --save-dev codeceptjs

Then create a npm script in package.json and use npm run codeceptjs command.

// package.json (excerpt)
"scripts”: {
"ng": "ng",
"start": "ng serve",
"build": "ng build",
"test": "ng test",
"lint": "ng lint",
"e2e": "ng e2e",
"codeceptjs": "codeceptjs run --steps"
},

run --steps command runs the tests with each steps printed to the console.

3. Create a config file for CodeceptJS

We can use npm run codeceptjs init to generate a config file. The command will ask some questions to fill in the file. Most of them we can use the default values. Some items we need to pay attention to are:

? What helpers do you want to use? Puppeteer
? [Protractor] Base url of site to be tested http://localhost:4200
? [Protractor] Root element of AngularJS application app-root
  • Select Puppeteer as a helper for CodeceptJS.
  • Change default base URL option from http://localhost to http://localhost:4200 as we are using this address for local dev server.
  • Change root element from body to app-root.

Note: these options depend on your Angular project settings.

The command then creates the config file codecept.json in the root directory of the project.

4. Writing the first test

We can use $ npm run codeceptjs generate:test (or $ npm run codeceptjs gt) to generate a test file. It will ask for the file name and the feature name to test. In this case, we want to test the Home page of the app so we enter home for file name and Home Page for feature name.

Let’s open the file and write our first test. We want to make sure there is a message “Welcome to app!” with the Angular logo on the page. Here is the test code.

// home_test.js
Feature('Home Page');
Scenario('Displaying welcome message', (I) => {
I.amOnPage('/');
I.see('Welcome to app!');
I.seeElement('img[alt="Angular Logo"]');

});

5. Running the tests

Update 2017–12–18: If you are using CodeceptJS 1.1+ and Puppeteer helper, these steps below to start Selenium server and WebDriver are no longer needed. You can run npm run codeceptjs and everything else should work.

To run the test, first, we need to have a Selenium server and a browser driver manager running. We can use webdriver-manager binary which comes installed already with Protractor to start Selenium server and browser driver manager to use Chrome with the Selenium server.

Create another npm script in package.json file:

"scripts": {
"codeceptjs": "codeceptjs run --steps",
"wd:start": "webdriver-manager update && webdriver-manager start --standalone"
},

Then run $ npm run wd:start command in the terminal. It prints a bunch of logs in the terminal but if we see the message “Selenium Server is up and running” then it is all good. Leave this terminal window open.

Open another terminal window and run $ npm start to start local development server of the app at http://localhost:4200 .

Finally, open another terminal and run $ npm run codeceptjs to run E2E test with CodeceptJS. It will open new Chrome window, run the tests, and display the test results in the terminal.

We now have CodeceptJS set up for E2E testing with an Angular 2+ project. There are much more APIs available we can use to write our tests. Make sure to check the documentation page on CodeceptJS website.

Check out part 2 of this post: Generate Beautiful Angular E2E Test Reports with Mochawesome.

Happy Testing. 💃 🤓