CodeceptJS
Reference: Helpers API | Demo
Modern Era Acceptance 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 too.
- Written from user's perspective. 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 these helpers:
And more to come...
Why CodeceptJS?
CodeceptJS is a successor of Codeception, a popular 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 synchronous.
Features
- Based on Mocha testing framework.
- Designed for scenario driven acceptance testing in BDD-style
- Uses ES6 natively without transpiler.
- Also plays nice with TypeScript.
- 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
If you want to write your tests using TypeScript just generate standard Type Definitions by executing:
codeceptjs def .
Later you can even automagically update Type Definitions to include your own custom helpers methods.
Note that CodeceptJS requires Node.js version 6.11 or later.
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.
Let's execute this test with run
command. Additional option --steps
will show us the running process. We recommend use --steps
or --debug
during development.
codeceptjs run --steps
This will produce an output:
CodeceptJS Demonstration --
test some forms
• I am on page "http://simple-form-bootstrap.plataformatec.com.br/documentation"
• I fill field "Email", "hello@world.com"
• I fill field "Password", "123456"
• I check option "Active"
• I check option "Male"
• I click "Create User"
• I see "User is valid"
• I dont see in current url "/documentation"
✓ OK in 17752ms
CodeceptJS has an ultimate feature to help you develop and debug you test.
You can pause execution of test in any place and use interactive shell to try different actions and locators.
Just add pause()
call at any place in a test and run it.
Interactive shell can be started outside test context by running:
codeceptjs shell
Actions
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 labels 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 preparation 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 = 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');
});
License
MIT © DavertMik
1.0.1
- Reporters improvements:
- Allows to execute multiple reporters
- Added Mochawesome helper
addMochawesomeContext
method to add custom data to mochawesome reports- Fixed Mochawesome context for failed screenshots.
- [WebDriverIO] improved click on context to match clickable element with a text inside. Fixes #647* [Nightmare] Added
refresh
function by @awhanks - fixed
Unhandled promise rejection (rejection id: 1): Error: Unknown wait type: pageLoad
- support for tests with retries in html report
- be sure that change window size and timeouts completes before test
- [Nightmare] Fixed
[Wrapped Error] "codeceptjs is not defined"
; Reinjectiing client scripts to a webpage on changes. - [Nightmare] Added more detailed error messages for
Wait*
methods - [Nightmare] Fixed adding screenshots to Mochawesome
- [Nightmare] Fix unique screenshots names in Nightmare
- Fixed CodeceptJS work with hooks in helpers to finish codeceptJS correctly if errors appears in helpers hooks
- Create a new session for next test If selenium grid error received
- Create screenshots for failed hooks from a Feature file
- Fixed
retries
option
1.0
CodeceptJS hits first stable release. CodeceptJS provides a unified API for web testing for Webdriverio, Protractor, and NightmareJS. Since 1.0 you can also test mobile applications in the similar manner with Appium.
Sample test:
I.seeAppIsInstalled("io.super.app");
I.click('~startUserRegistrationCD');
I.fillField('~email of the customer', 'Nothing special'));
I.see('davert@codecept.io', '~email of the customer'));
I.clearField('~email of the customer'));
I.dontSee('Nothing special', '~email of the customer'));
We also introduced two new helpers for data management.
Using them you can easily prepare and cleanup data for your tests using public REST API.
Sample test
// create a user using data factories and REST API
I.have('user', { name: 'davert', password: '123456' });
// use it to login
I.amOnPage('/login');
I.fillField('login', 'davert');
I.fillField('password', '123456');
I.click('Login');
I.see('Hello, davert');
// user will be removed after the test
Next notable feature is SmartWait for WebDriverIO, Protractor, SeleniumWebdriver. When smartwait
option is set, script will wait for extra milliseconds to locate an element before failing. This feature uses implicit waits of Selenium but turns them on only in applicable pieces. For instance, implicit waits are enabled for seeElement
but disabled for dontSeeElement
Changelog
- Minimal NodeJS version is 6.11.1 LTS
- Use
within
command with generators. - Data Driven Tests introduced.
- Print execution time per step in
--debug
mode. #591 by @APshenkin - [WebDriverIO][Protractor][Nightmare] Added
disableScreenshots
option to disable screenshots on fail by @Apshenkin - [WebDriverIO][Protractor][Nightmare] Added
uniqueScreenshotNames
option to generate unique names for screenshots on failure by @Apshenkin - [WebDriverIO][Nightmare] Fixed click on context;
click('text', '#el')
will throw exception if text is not found inside #el
. - [WebDriverIO][Protractor][SeleniumWebdriver] SmartWait introduced.
- [WebDriverIO][Protractor][Nightmare]Fixed
saveScreenshot
for PhantomJS, fullPageScreenshots
option introduced by @HughZurname #549 - [Appium] helper introduced by @APshenkin
- [REST] helper introduced by @atrevino in #504
- [WebDriverIO][SeleniumWebdriver] Fixed "windowSize": "maximize" for Chrome 59+ version #560 by @APshenkin
- [Nightmare] Fixed restarting by @APshenkin #581
- [WebDriverIO] Methods added by @APshenkin:
- Use mkdirp to create output directory. #592 by @vkramskikh
- [WebDriverIO] Fixed
seeNumberOfVisibleElements
by @BorisOsipov #574 - Lots of fixes for promise chain by @APshenkin #568
- Fix #543- After block not properly executed if Scenario fails
- Expected behavior in promise chains:
_beforeSuite
hooks from helpers -> BeforeSuite
from test -> _before
hooks from helpers -> Before
from test - > Test steps -> _failed
hooks from helpers (if test failed) -> After
from test -> _after
hooks from helpers -> AfterSuite
from test -> _afterSuite
hook from helpers. - if during test we got errors from any hook (in test or in helper) - stop complete this suite and go to another
- if during test we got error from Selenium server - stop complete this suite and go to another
- [WebDriverIO][Protractor] if
restart
option is false - close all tabs expect one in _after
. - Complete
_after
, _afterSuite
hooks even After/AfterSuite from test was failed - Don't close browser between suites, when
restart
option is false. We should start browser only one time and close it only after all tests. - Close tabs and clear local storage, if
keepCookies
flag is enabled
- Fix TypeError when using babel-node or ts-node on node.js 7+ #586 by @vkramskikh
- [Nightmare] fixed usage of
_locate
Special thanks to Andrey Pshenkin for his work on this release and the major improvements.