Build Status:

Appium Helper:

Web Helper:

CodeceptJS

Reference:Helpers API

Supercharged E2E Testing

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:

• Synchronous.You don't need to care about callbacks or promises or test scenarios which are linear. But, your tests should be linear.
• Written fromuser's perspective.Every action is a method ofI.That makes test easy to read, write and maintain even for non-tech persons.
• BackendAPI agnostic.We don't know which WebDriver implementation is running this test.

CodeceptJS usesHelpermodules to provide actions toIobject. Currently, CodeceptJS has these helpers:

• Playwright- is a Node library to automate the Chromium, WebKit and Firefox browsers with a single API.
• Puppeteer- uses Google Chrome's Puppeteer for fast headless testing.
• WebDriver- useswebdriverioto run tests via WebDriver or Devtools protocol.
• TestCafe- cheap and fast cross-browser test automation.
• Appium- formobile testingwith Appium
• Detox- This is a wrapper on top of Detox library, aimed to unify testing experience for CodeceptJS framework. Detox provides a grey box testing for mobile applications, playing especially well for React Native apps.

And more to come...

Why CodeceptJS?

CodeceptJS is a successor ofCodeception,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.

Features

• 🪄AI-poweredwith GPT features to assist and heal failing tests.
• ☕ Based onMochatesting framework.
• 💼 Designed for scenario driven acceptance testing in BDD-style.
• 💻 Uses ES6 natively without transpiler.
• Also plays nice with TypeScript.
• </> 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.

Installation

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 customhelpers methods.

Note:

• CodeceptJS requires Node.js version12+or later.

Usage

Learn CodeceptJS by examples. Let's assume we have CodeceptJS installed and WebDriver 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.br/documentation');
I.fillField('Email','hello@world ');
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 byIobject; assertions functions start withseefunction. In these examples all methods ofIare taken from WebDriver helper, seereferenceto learn how to use them.

Let's execute this test withruncommand. Additional option--stepswill show us the running process. We recommend use--stepsor--debugduring development.

npx codeceptjs run --steps

This will produce an output:

CodeceptJS Demonstration --
testsome forms
• I am on page"http://simple-form-bootstrap.plataformatec.br/documentation"
• I fill field"Email","hello@world"
• I fill field"Password","****"
• I check option"Active"
• I check option"Male"
• I click"Create User"
• I see"User is valid"
• I dont seeincurrent url"/documentation"
✓ OKin17752ms

CodeceptJS has an ultimate feature to help you develop and debug your test. You canpause execution of test in any place and use interactive shellto try different actions and locators. Just addpause()call at any place in a test and run it.

Interactive shell can be started outside test context by running:

npx codeceptjs shell

Actions

We filled form withfillFieldmethods, which located form elements by their label. The same way you can locate element by name,CSSorXPathlocators in tests:

// by name
I.fillField('user_basic[email]','hello@world ');
// by CSS
I.fillField('#user_basic_email','hello@world ');
// don't make us guess locator type, specify it
I.fillField({css:'#user_basic_email'},'hello@world ');

Other methods likecheckOption,andclickwork in a similar manner. They can take labels or CSS or XPath locators to find elements to interact.

Assertions

Assertions start withseeordontSeeprefix. 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.

Grabbers

In case you need to return a value from a webpage and use it directly in test, you should use methods withgrabprefix. They are expected to be used insideasync/awaitfunctions, and their results will be available in test:

Feature('CodeceptJS Demonstration');

Scenario('test page title',async({I})=>{
I.amOnPage('http://simple-form-bootstrap.plataformatec.br/documentation');
consttitle=awaitI.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.

Before/After

Common preparation steps like opening a web page, logging in a user, can be placed inBeforeorBackground:

const{I}=inject();

Feature('CodeceptJS Demonstration');

Before(()=>{// or Background
I.amOnPage('http://simple-form-bootstrap.plataformatec.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');
});

PageObjects

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 nameddocsPage:

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.br/documentation');
});

Scenario('test some forms',({I,docsPage})=>{
docsPage.sendForm('hello@world ','123456');
I.see('User is valid');
I.dontSeeInCurrentUrl('/documentation');
});

When using Typescript, replacemodule.exportswithexportfor autocompletion.

Contributing

• Contributing Guide

• Code of conduct

Contributors

Thanks all to those who are and will have contributing to this awesome project!

License

MIT ©CodeceptJS Team