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
tohttp://localhost:4200
as we are using this address for local dev server. - Change root element from
body
toapp-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.jsFeature('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. 💃 🤓