What is codeceptjs?
CodeceptJS is an end-to-end testing framework for Node.js that simplifies the process of writing and running tests for web applications. It supports various testing engines like WebDriver, Puppeteer, TestCafe, and more, allowing for flexible and powerful test automation.
What are codeceptjs's main functionalities?
End-to-End Testing
CodeceptJS allows you to write end-to-end tests in a simple and readable format. This example demonstrates a basic login test where the user navigates to the login page, fills in the username and password, clicks the login button, and verifies that the welcome message is displayed.
const { I } = inject();
Feature('Login');
Scenario('test login', (I) => {
I.amOnPage('/login');
I.fillField('Username', 'user');
I.fillField('Password', 'password');
I.click('Login');
I.see('Welcome, user');
});
Page Object Model
CodeceptJS supports the Page Object Model (POM) design pattern, which helps in organizing and maintaining test code. This example shows a LoginPage class that encapsulates the elements and actions related to the login page, making the test code more modular and reusable.
class LoginPage {
constructor() {
this.fields = {
username: 'input[name="username"]',
password: 'input[name="password"]'
};
this.buttons = {
login: 'button[type="submit"]'
};
}
login(username, password) {
I.fillField(this.fields.username, username);
I.fillField(this.fields.password, password);
I.click(this.buttons.login);
}
}
module.exports = new LoginPage();
Data-Driven Testing
CodeceptJS supports data-driven testing, allowing you to run the same test with different sets of data. This example demonstrates how to create a data table with multiple user credentials and run the login test for each set of credentials.
const { I } = inject();
Feature('Login');
const users = new DataTable(['username', 'password']);
users.add(['user1', 'password1']);
users.add(['user2', 'password2']);
Data(users).Scenario('test login with multiple users', (I, current) => {
I.amOnPage('/login');
I.fillField('Username', current.username);
I.fillField('Password', current.password);
I.click('Login');
I.see('Welcome, ' + current.username);
});
Other packages similar to codeceptjs
cypress
Cypress is a popular end-to-end testing framework that provides a fast, reliable, and easy-to-use testing experience. It offers features like time travel, real-time reloads, and automatic waiting. Compared to CodeceptJS, Cypress has a more modern and user-friendly interface but is limited to running tests in a browser environment.
nightwatch
Nightwatch.js is an end-to-end testing framework that uses the W3C WebDriver API to perform browser automation. It is known for its simplicity and ease of setup. Compared to CodeceptJS, Nightwatch.js is more focused on WebDriver-based testing and may require more configuration for advanced use cases.
webdriverio
WebdriverIO is a versatile testing framework that supports both WebDriver and DevTools protocols. It offers a wide range of plugins and integrations, making it highly customizable. Compared to CodeceptJS, WebdriverIO provides more flexibility and control over the testing process but may have a steeper learning curve.
CodeceptJs
Reference: Helpers API
Modern Era Aceptance Testing Framework for NodeJS
CodeceptJS is a new testing framework for end-to-end testing with WebDriver (or others).
It abstracts browser interaction to simple steps which is written from a user perspective.
A simple test that verifies that "Welcome" text is present on a main page of a site will look like:
Feature('CodeceptJS demo');
Scenario('check Welcome page on site', (I) => {
I.amOnPage('/');
I.see('Welcome');
}
Codeception tests are:
- Synchronous. You don't need to care about callbacks, or promises, test scenarios are linear, your test should be to.
- Written from user's perspecitve. Every action is a method of
I
. That makes test easy to read, write and maintain even for non-tech persons. - backend API agnostic. We don't know which WebDriver implementation is running this test. We can easily switch from WebDriverIO to Protractor or PhantomJS.
Codeception uses Helper modules to provide actions to I
object. Currently CodeceptJS has two helpers:
And more to come...
Why CodeceptJS?
CodeceptJS is a successor of Codeception, a popoular full-stack testing framework for PHP.
With CodeceptJS your scenario-driven functional and acceptance tests will be as simple and clean as they can be.
You don't need to worry about asynchronous nature of NodeJS or about various APIs of Selenium, PhantomJS, Protractor, etc,
as CodeceptJS unifies them and makes them work as they were sycnhronous.
Features
- Based on Mocha testing framework.
- Designed for scenario driven acceptance testing in BDD-style
- Uses ES6 natively without transpiler.
- Selenium WebDriver integration using webdriverio.
- Smart locators: use names, labels, matching text, CSS or XPath to locate elements.
- Interactive debugging shell: pause test at any point and try different commands in a browser.
- Easily create tests, pageobjects, stepobjects with CLI generators.
Install
$ npm install -g codeceptjs
Move to directory where you'd like to have your tests (and codeceptjs config) stored, and run
codeceptjs init
to create and configure test environment. It is recommended to select WebDriverIO from the list of helpers,
if you need to write Selenium WebDriver tests.
After that create your first test by executing:
codeceptjs generate test
Now test is created and can be executed with
codeceptjs run
Usage
Learn CodeceptJS by examples. Let's assume we have CodeceptJS installed and WebDriverIO helper enabled.
Basics
Let's see how we can handle basic form testing:
Feature('CodeceptJS Demonstration');
Scenario('test some forms', (I) => {
I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
I.fillField('Email', 'hello@world.com');
I.fillField('Password', '123456');
I.checkOption('Active');
I.checkOption('Male');
I.click('Create User');
I.see('User is valid');
I.dontSeeInCurrentUrl('/documentation');
});
All actions are performed by I object; assertions functions start with see
function.
In this examples all methods of I are taken from WebDriverIO helper, see reference to learn how to use them.
We filled form with fillField
methods, which located form elements by their label.
The same way you can locate element by name, CSS or XPath locators in tests:
I.fillField('user_basic[email]', 'hello@world.com');
I.fillField('#user_basic_email', 'hello@world.com');
I.fillField({css: '#user_basic_email'}, 'hello@world.com');
Other methods like checkOption
, and click
work in a similar manner. They can take lables or CSS or XPath locators to find elements to interact.
Assertions
Assertions start with see
or dontSee
prefix. In our case we are asserting that string 'User is valid' is somewhere in a webpage.
However, we can narrow the search to particular element by providing a second parameter:
I.see('User is valid');
I.see('User is valid', '.alert-success');
In this case 'User is valid' string will be searched only inside elements located by CSS .alert-success
.
Grabbers
In case you need to return a value from a webpage and use it directly in test, you should use methods with grab
prefix.
They are expected to be used inside a generator functions, and their results will be available in test:
var assert = require('assert');
Feature('CodeceptJS Demonstration');
Scenario('test page title', function*(I) {
I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
var title = yield I.grabTitle();
assert.equal(title, 'Example application with SimpleForm and Twitter Bootstrap');
});
The same way you can grab text, attributes, or form values and use them in next test steps.
Before/After
Common preperation steps like opening a web page, logging in a user, can be placed in Before
or Background
:
Feature('CodeceptJS Demonstration');
Before((I) => {
I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
});
Scenario('test some forms', (I) => {
I.click('Create User');
I.see('User is valid');
I.dontSeeInCurrentUrl('/documentation');
});
Scenario('test title', (I) => {
I.seeInTitle('Example application');
});
PageObjects
CodeceptJS provides the most simple way to create and use page objects in your test.
You can create one by running
codeceptjs generate pageobject
It will create a page object file for you and add it to config.
Let's assume we created one named docsPage
:
'use strict';
let I;
module.exports = {
_init() {
I = require('codeceptjs/actor')();
},
fields: {
email: '#user_basic_email',
password: '#user_basic_password'
},
submitButton: {css: '#new_user_basic input[type=submit]'},
sendForm(email, password) {
I.fillField(this.fields.email, email);
I.fillField(this.fields.password, password);
I.click(this.submitButton);
}
}
You can easily inject it to test by providing its name in test arguments:
Feature('CodeceptJS Demonstration');
Before((I) => {
I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
});
Scenario('test some forms', (I, docsPage) => {
docsPage.sendForm('hello@world.com','123456);
I.see('User is valid');
I.dontSeeInCurrentUrl('/documentation');
});
Current State
CodeceptJS is in its early days. Any feedback, issues, and pull requests are welcome. Try i, and if you like it - help us make it better!
License
MIT © DavertMik