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 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 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.
CodeceptJS uses Helper modules to provide actions to I
object. 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 - uses webdriverio to run tests via WebDriver protocol.
- TestCafe - cheap and fast cross-browser test automation.
- Appium - for mobile testing with 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 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, Puppeteer, TestCafe, etc. as CodeceptJS unifies them and makes them work as they are synchronous.
Features
- 🪄 AI-powered with GPT features to assist and heal failing tests
- Based on Mocha testing 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.
Install
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:
- CodeceptJS requires Node.js version
12+
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.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 this 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
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 async/await functions, and their results will be available in test:
const assert = require('assert');
Feature('CodeceptJS Demonstration');
Scenario('test page title', async ({ I }) => {
I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
const title = await 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
:
const { I } = inject();
Feature('CodeceptJS Demonstration');
Before(() => {
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');
});
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 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 }) => {
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.
Contributing
Contributors
Thanks all to those who are and will have contributing to this awesome project!
License
MIT © CodeceptJS Team
3.5.7
Thanks all to those who contributed to make this release!
🐛 Bug Fixes
- Bump playwright to 1.39.0 - run
npx playwright install
to install the browsers as starting from 1.39.0 browsers are not installed automatically (#3924) - by @KobeNguyenT - fix(playwright): some wait functions draw error due to switchTo iframe (#3918) - by @KobeNguyenT
- fix(appium): AppiumTestDistribution/appium-device-farm requires 'platformName' (#3950) - by @rock-tran
- fix: autologin with empty fetch (#3947) - by @andonary
- fix(cli): customLocator draws error in dry-mode (#3940) - by @KobeNguyenT
- fix: ensure docs include @returns Promise<void> where appropriate (#3954) - by @fwouts
- fix: long text in data table cuts off (#3936) - by @KobeNguyenT
Funktionalität: Faker examples
Szenariogrundriss: Atualizar senha do usuário
Angenommen que estou logado via REST com o usuário "<customer>"
| protocol | https: |
| hostname | https://cucumber.io/docs/gherkin/languages/ |
Faker examples --
Atualizar senha do usuário {"product":"{{vehicle.vehicle}}","customer":"Dr. {{name.findName}}","price":"{{commerce.price}}","cashier":"cashier 2"}
On Angenommen: que estou logado via rest com o usuário "dr. {{name.find name}}"
protocol | https:
hostname | https://cucumber.io/docs/gherkin/languages/
Dr. {{name.findName}}
✔ OK in 13ms
- fix(playwright): move to waitFor (#3933) - by @KobeNguyenT
- fix: relax grabCookie type (#3919) - by @KobeNguyenT
- fix: proceedSee error when being called inside within (#3939) - by @KobeNguyenT
- fix: rename haveRequestHeaders of ppt and pw helpers (#3937) - by @KobeNguyenT
Renamed haveRequestHeaders of Puppeteer, Playwright helper so that it would not confuse the REST helper.
Puppeteer: setPuppeteerRequestHeaders
Playwright: setPlaywrightRequestHeaders
- improvement: handle the way to load apifactory nicely (#3941) - by @KobeNguyenT
With this fix, we could now use the following syntax:
export = new Factory()
.attr('name', () => faker.name.findName())
.attr('job', () => 'leader');
export default new Factory()
.attr('name', () => faker.name.findName())
.attr('job', () => 'leader');
modules.export = new Factory()
.attr('name', () => faker.name.findName())
.attr('job', () => 'leader');
📖 Documentation
- docs(appium): update to v2 (#3932) - by @KobeNguyenT
- docs: improve BDD Gherkin docs (#3938) - by @KobeNguyenT
- Other docs improvements
🛩️ Features
- feat(puppeteer): support trace recording - by @KobeNguyenT
[Trace Recording Customization]
Trace recording provides complete information on test execution and includes screenshots, and network requests logged during run. Traces will be saved to output/trace
trace: enables trace recording for failed tests; trace are saved into output/trace folder
keepTraceForPassedTests: - save trace for passed tests
- feat: expect helper (#3923) - by @KobeNguyenT
* This helper allows performing assertions based on Chai.
*
* ### Examples
*
* Zero-configuration when paired with other helpers like REST, Playwright:
*
* ```js
* // inside codecept.conf.js
*{
* helpers: {
* Playwright: {...},
* ExpectHelper: {},
* }
Expect Helper
#expectEqual
#expectNotEqual
#expectContain
#expectNotContain
#expectStartsWith
#expectNotStartsWith
#expectEndsWith
#expectNotEndsWith
#expectJsonSchema
#expectHasProperty
#expectHasAProperty
#expectToBeA
#expectToBeAn
#expectMatchRegex
#expectLengthOf
#expectTrue
#expectEmpty
#expectFalse
#expectAbove
#expectBelow
#expectLengthAboveThan
#expectLengthBelowThan
#expectLengthBelowThan
#expectDeepMembers
#expectDeepIncludeMembers
#expectDeepEqualExcluding
#expectLengthBelowThan
- feat: run-workers with multiple browsers output folders - by @KobeNguyenT
- feat: introduce new Playwright methods - by @hatufacci
- grabCheckedElementStatus
- grabDisabledElementStatus
- feat: gherkin supports i18n (#3934) - by @KobeNguyenT
#language: de
Funktionalität: Checkout-Prozess
Um Produkte zu kaufen
Als Kunde
Möchte ich in der Lage sein, mehrere Produkte zu kaufen
@i18n
Szenariogrundriss: Bestellrabatt
Angenommen ich habe ein Produkt mit einem Preis von <price>$ in meinem Warenkorb
Und der Rabatt für Bestellungen über $20 beträgt 10 %
Wenn ich zur Kasse gehe
Dann sollte ich den Gesamtpreis von "<total>" $ sehen
Beispiele:
| price | total |
| 10 | 10.0 |
- feat(autoLogin): improve the check method (#3935) - by @KobeNguyenT
Instead of asserting on page elements for the current user in check, you can use the session you saved in fetch
autoLogin: {
enabled: true,
saveToFile: true,
inject: 'login',
users: {
admin: {
login: async (I) => { // If you use async function in the autoLogin plugin
const phrase = await I.grabTextFrom('#phrase')
I.fillField('username', 'admin'),
I.fillField('password', 'password')
I.fillField('phrase', phrase)
},
check: (I, session) => {
// Throwing an error in `check` will make CodeceptJS perform the login step for the user
if (session.profile.email !== the.email.you.expect@some-mail.com) {
throw new Error ('Wrong user signed in');
}
},
}
}
}
Scenario('login', async ( {I, login} ) => {
await login('admin') // you should use `await`
})