codeceptjs
Advanced tools
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.
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);
});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.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 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.
Build Status:
Appium Helper:
Web Helper:
Reference: Helpers API
CodeceptJS is a new testing framework for end-to-end testing with WebDriver (or others). It abstracts browser interaction to simple steps that are written from a user's perspective. A simple test that verifies the "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');
});
CodeceptJS tests are:
I. That makes test easy to read, write and maintain even for non-tech persons.CodeceptJS uses Helper modules to provide actions to I object. Currently, CodeceptJS has these helpers:
And more to come...
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 Playwright, Selenium, Puppeteer, TestCafe, etc. as CodeceptJS unifies them and makes them work as they are synchronous.
npm i codeceptjs --save
Move to directory where you'd like to have your tests (and CodeceptJS config) stored, and execute:
npx codeceptjs init
to create and configure test environment. It is recommended to select WebDriver from the list of helpers, if you need to write Selenium WebDriver tests.
After that create your first test by executing:
npx codeceptjs generate:test
Now test is created and can be executed with
npx codeceptjs run
If you want to write your tests using TypeScript just generate standard Type Definitions by executing:
npx codeceptjs def .
Later you can even automagically update Type Definitions to include your own custom helpers methods.
Note:
12+ or later.Learn CodeceptJS by examples. Let's assume we have CodeceptJS installed and WebDriver helper enabled.
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', secret('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 these examples all methods of I are taken from WebDriver 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.
npx 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", "****"
• 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 your 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:
npx codeceptjs shell
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:
// by name
I.fillField('user_basic[email]', 'hello@world.com');
// by CSS
I.fillField('#user_basic_email', 'hello@world.com');
// don't make us guess locator type, specify it
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 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');
// better to specify context:
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.
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 async/await functions, and their results will be available in test:
Feature('CodeceptJS Demonstration');
Scenario('test page title', async ({ I }) => {
I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
const title = await I.grabTitle();
I.expectEqual(title, 'Example application with SimpleForm and Twitter Bootstrap'); // Avaiable with Expect helper. -> https://codecept.io/helpers/Expect/
});
The same way you can grab text, attributes, or form values and use them in next test steps.
Common preparation steps like opening a web page, logging in a user, can be placed in Before or Background:
const { I } = inject();
Feature('CodeceptJS Demonstration');
Before(() => { // or Background
I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
});
Scenario('test some forms', () => {
I.click('Create User');
I.see('User is valid');
I.dontSeeInCurrentUrl('/documentation');
});
Scenario('test title', () => {
I.seeInTitle('Example application');
});
CodeceptJS provides the most simple way to create and use page objects in your test. You can create one by running
npx codeceptjs generate pageobject
It will create a page object file for you and add it to the config.
Let's assume we created one named docsPage:
const { I } = inject();
module.exports = {
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 }) => { // or Background
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');
});
When using Typescript, replace module.exports with export for autocompletion.
Thanks all to those who are and will have contributing to this awesome project!
MIT © CodeceptJS Team
3.5.10
❤️ Thanks all to those who contributed to make this release! ❤️
🛩️ Features
Now we expose the WebElements that are returned by the WebHelper and you could make the subsequence actions on them.
// Playwright helper would return the Locator
I.amOnPage('/form/focus_blur_elements');
const webElements = await I.grabWebElements('#button');
webElements[0].click();
Replaying from HAR
// Replay API requests from HAR.
// Either use a matching response from the HAR,
// or abort the request if nothing matches.
I.replayFromHar('./output/har/something.har', { url: "*/**/api/v1/fruits" });
I.amOnPage('https://demo.playwright.dev/api-mocking');
I.see('CodeceptJS');
[Parameters]
harFilePath [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) Path to recorded HAR file
opts [object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)? [Options for replaying from HAR](https://playwright.dev/docs/api/class-page#page-route-from-har)
A HAR file is an HTTP Archive file that contains a record of all the network requests that are made when a page is loaded.
It contains information about the request and response headers, cookies, content, timings, and more.
You can use HAR files to mock network requests in your tests. HAR will be saved to output/har.
More info could be found here https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har.
...
recordHar: {
mode: 'minimal', // possible values: 'minimal'|'full'.
content: 'embed' // possible values: "omit"|"embed"|"attach".
}
...
await I.amOnPage('/form/select');
await I.selectOption('Select your age', '21-');
🐛 Bug Fixes
Emit the new event: event.workers.result.
CodeceptJS also exposes the env var `process.env.RUNS_WITH_WORKERS` when running tests with run-workers command so that you could handle the events better in your plugins/helpers.
const { event } = require('codeceptjs');
module.exports = function() {
// this event would trigger the `_publishResultsToTestrail` when running `run-workers` command
event.dispatcher.on(event.workers.result, async () => {
await _publishResultsToTestrail();
});
// this event would not trigger the `_publishResultsToTestrail` multiple times when running `run-workers` command
event.dispatcher.on(event.all.result, async () => {
// when running `run` command, this env var is undefined
if (!process.env.RUNS_WITH_WORKERS) await _publishResultsToTestrail();
});
}
replaced minify library with a modern and more secure fork. Fixes html-minifier@4.0.0 Regular Expression Denial of Service vulnerability #3829
AI class is implemented as singleton
refactored heal.js plugin to work on edge cases
add configuration params on number of fixes performed by ay heal
improved recorder class to add more verbose log
improved recorder class to ignore some of errors
Fixed this error:
locator.isVisible: Unexpected token "s" while parsing selector ":has-text('Were you able to resolve the resident's issue?') >> nth=0"
at Playwright.waitForText (node_modules\codeceptjs\lib\helper\Playwright.js:2584:79)
Currently inside the _before() of helpers for example Playwright, the retries is set there, however, when retryFailedStep plugin is enabled, the retries of recorder is still using the value from _before() not the value from retryFailedStep plugin.
Fix:
- introduce the process.env.FAILED_STEP_RETIRES which could be access everywhere as the helper won't know anything about the plugin.
- set default retries of Playwright to 3 to be on the same page with Puppeteer.
When test title doesn't have the data in examples:
Feature: Faker examples
Scenario Outline: Below are the users
Examples:
| user | role |
| John | admin |
| Tim | client |
Faker examples --
[1] Starting recording promises
Timeouts:
Below are the users {"user":"John","role":"admin"}
✔ OK in 4ms
Below are the users {"user":"Tim","role":"client"}
✔ OK in 1ms
When test title includes the data in examples:
Feature: Faker examples
Scenario Outline: Below are the users - <user> - <role>
Examples:
| user | role |
| John | admin |
| Tim | client |
Faker examples --
[1] Starting recording promises
Timeouts:
Below are the users - John - admin
✔ OK in 4ms
Below are the users - Tim - client
✔ OK in 1ms
📖 Documentation
FAQs
Supercharged End 2 End Testing Framework for NodeJS
The npm package codeceptjs receives a total of 133,406 weekly downloads. As such, codeceptjs popularity was classified as popular.
We found that codeceptjs demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.