{"id":15177247,"url":"https://github.com/codeceptjs/codeceptjs","last_synced_at":"2026-04-08T14:32:37.243Z","repository":{"id":37846862,"uuid":"46641250","full_name":"codeceptjs/CodeceptJS","owner":"codeceptjs","description":"Supercharged End 2 End Testing Framework for NodeJS","archived":false,"fork":false,"pushed_at":"2025-04-22T05:51:18.000Z","size":58494,"stargazers_count":4168,"open_issues_count":202,"forks_count":737,"subscribers_count":94,"default_branch":"3.x","last_synced_at":"2025-04-23T20:59:14.936Z","etag":null,"topics":["acceptance-testing","bdd","bdd-framework","codeceptjs","e2e-tests","end-to-end-testing","graphql-testing","hacktoberfest","javascript","nodejs","pageobject","playwright","selenium","selenium-webdriver","testing","webdriver","webdriverio"],"latest_commit_sha":null,"homepage":"http://codecept.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeceptjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":"codeceptjs","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-11-22T01:14:36.000Z","updated_at":"2025-04-23T08:55:12.000Z","dependencies_parsed_at":"2023-09-29T08:50:26.235Z","dependency_job_id":"2bf2d501-2585-475c-b6a9-dbc0272710da","html_url":"https://github.com/codeceptjs/CodeceptJS","commit_stats":{"total_commits":2631,"total_committers":420,"mean_commits":6.264285714285714,"dds":0.7491448118586088,"last_synced_commit":"cc8285237f0fbf1c87c53cf4572acc06d4ce51f7"},"previous_names":["codeception/codeceptjs"],"tags_count":135,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2FCodeceptJS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2FCodeceptJS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2FCodeceptJS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeceptjs%2FCodeceptJS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeceptjs","download_url":"https://codeload.github.com/codeceptjs/CodeceptJS/tar.gz/refs/heads/3.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250514767,"owners_count":21443208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acceptance-testing","bdd","bdd-framework","codeceptjs","e2e-tests","end-to-end-testing","graphql-testing","hacktoberfest","javascript","nodejs","pageobject","playwright","selenium","selenium-webdriver","testing","webdriver","webdriverio"],"created_at":"2024-09-27T14:04:26.502Z","updated_at":"2026-04-08T14:32:37.231Z","avatar_url":"https://github.com/codeceptjs.png","language":"JavaScript","readme":"[![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg)](https://stand-with-ukraine.pp.ua)\n\n[\u003cimg src=\"https://img.shields.io/badge/slack-@codeceptjs-purple.svg?logo=slack\"\u003e](https://join.slack.com/t/codeceptjs/shared_invite/enQtMzA5OTM4NDM2MzA4LWE4MThhN2NmYTgxNTU5MTc4YzAyYWMwY2JkMmZlYWI5MWQ2MDM5MmRmYzZmYmNiNmY5NTAzM2EwMGIwOTNhOGQ) [\u003cimg src=\"https://img.shields.io/badge/discourse-codeceptjs-purple\"\u003e](https://codecept.discourse.group) [![NPM version][npm-image]][npm-url] [\u003cimg src=\"https://img.shields.io/badge/dockerhub-images-blue.svg?logo=codeceptjs\"\u003e](https://hub.docker.com/r/codeceptjs/codeceptjs)\n[![AI features](https://img.shields.io/badge/AI-features?logo=openai\u0026logoColor=white)](https://github.com/codeceptjs/CodeceptJS/edit/3.x/docs/ai.md) [![StandWithUkraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/badges/StandWithUkraine.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)\n\n## Build Status\n\n| Type      | Engine     | Status                                                                                                                                                                                              |\n| --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 🌐 Web    | Playwright | [![Playwright Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml)               |\n| 🌐 Web    | Puppeteer  | [![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)                  |\n| 🌐 Web    | WebDriver  | [![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)                  |\n| 🌐 Web    | TestCafe   | [![TestCafe Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml)                     |\n| 📱 Mobile | Appium     | [![Appium Tests - Android](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml) |\n\n# CodeceptJS [![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)\n\nReference: [Helpers API](https://github.com/codeceptjs/CodeceptJS/tree/master/docs/helpers)\n\n## Supercharged E2E Testing\n\nCodeceptJS is a new testing framework for end-to-end testing with WebDriver (or others).\nIt abstracts browser interaction to simple steps that are written from a user's perspective.\nA simple test that verifies the \"Welcome\" text is present on a main page of a site will look like:\n\n```js\nFeature('CodeceptJS demo')\n\nScenario('check Welcome page on site', ({ I }) =\u003e {\n  I.amOnPage('/')\n  I.see('Welcome')\n})\n```\n\nCodeceptJS tests are:\n\n- **Synchronous**. You don't need to care about callbacks or promises or test scenarios which are linear. But, your tests should be linear.\n- 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.\n- Backend **API agnostic**. We don't know which WebDriver implementation is running this test.\n\nCodeceptJS uses **Helper** modules to provide actions to `I` object. Currently, CodeceptJS has these helpers:\n\n- [**Playwright**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Playwright.md) - is a Node library to automate the Chromium, WebKit and Firefox browsers with a single API.\n- [**Puppeteer**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Puppeteer.md) - uses Google Chrome's Puppeteer for fast headless testing.\n- [**WebDriver**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) - uses [webdriverio](http://webdriver.io/) to run tests via WebDriver or Devtools protocol.\n- [**TestCafe**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/TestCafe.md) - cheap and fast cross-browser test automation.\n- [**Appium**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Appium.md) - for **mobile testing** with Appium\n- [**Detox**](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/Detox.md) - 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.\n\nAnd more to come...\n\n## Why CodeceptJS?\n\nCodeceptJS is a successor of [Codeception](http://codeception.com), a popular full-stack testing framework for PHP.\nWith CodeceptJS your scenario-driven functional and acceptance tests will be as simple and clean as they can be.\nYou 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.\n\n## Features\n\n- 🪄 **AI-powered** with GPT features to assist and heal failing tests.\n- ☕ Based on [Mocha](https://mochajs.org/) testing framework.\n- 💼 Designed for scenario driven acceptance testing in BDD-style.\n- 💻 Uses ES6 natively without transpiler.\n- Also plays nice with TypeScript.\n- \u003c/\u003e Smart locators: use names, labels, matching text, CSS or XPath to locate elements.\n- 🌐 Interactive debugging shell: pause test at any point and try different commands in a browser.\n- ⚡ **Parallel testing** with dynamic test pooling for optimal load balancing and performance.\n- 📊 **Built-in HTML Reporter** with interactive dashboard, step-by-step execution details, and comprehensive test analytics.\n- Easily create tests, pageobjects, stepobjects with CLI generators.\n\n## Installation\n\n```sh\nnpm i codeceptjs --save\n```\n\nMove to directory where you'd like to have your tests (and CodeceptJS config) stored, and execute:\n\n```sh\nnpx codeceptjs init\n```\n\nto create and configure test environment. It is recommended to select WebDriver from the list of helpers, if you need to write Selenium WebDriver tests.\n\nAfter that create your first test by executing:\n\n```sh\nnpx codeceptjs generate:test\n```\n\nNow test is created and can be executed with\n\n```sh\nnpx codeceptjs run\n```\n\nIf you want to write your tests using TypeScript just generate standard Type Definitions by executing:\n\n```sh\nnpx codeceptjs def .\n```\n\nLater you can even automagically update Type Definitions to include your own custom [helpers methods](docs/helpers.md).\n\nNote:\n\n- CodeceptJS requires Node.js version `12+` or later.\n\n## Usage\n\nLearn CodeceptJS by examples. Let's assume we have CodeceptJS installed and WebDriver helper enabled.\n\n### Basics\n\nLet's see how we can handle basic form testing:\n\n```js\nFeature('CodeceptJS Demonstration')\n\nScenario('test some forms', ({ I }) =\u003e {\n  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation')\n  I.fillField('Email', 'hello@world.com')\n  I.fillField('Password', secret('123456'))\n  I.checkOption('Active')\n  I.checkOption('Male')\n  I.click('Create User')\n  I.see('User is valid')\n  I.dontSeeInCurrentUrl('/documentation')\n})\n```\n\nAll actions are performed by `I` object; assertions functions start with `see` function.\nIn these examples all methods of `I` are taken from WebDriver helper, see [reference](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) to learn how to use them.\n\nLet's execute this test with `run` command. Additional option `--steps` will show us the running process. We recommend use `--steps` or `--debug` during development.\n\n```sh\nnpx codeceptjs run --steps\n```\n\nThis will produce an output:\n\n```sh\nCodeceptJS Demonstration --\n test some forms\n • I am on page \"http://simple-form-bootstrap.plataformatec.com.br/documentation\"\n • I fill field \"Email\", \"hello@world.com\"\n • I fill field \"Password\", \"****\"\n • I check option \"Active\"\n • I check option \"Male\"\n • I click \"Create User\"\n • I see \"User is valid\"\n • I dont see in current url \"/documentation\"\n ✓ OK in 17752ms\n```\n\nCodeceptJS has an ultimate feature to help you develop and debug your test.\nYou can **pause execution of test in any place and use interactive shell** to try different actions and locators.\nJust add `pause()` call at any place in a test and run it.\n\nInteractive shell can be started outside test context by running:\n\n```sh\nnpx codeceptjs shell\n```\n\n### Actions\n\nWe filled form with `fillField` methods, which located form elements by their label.\nThe same way you can locate element by name, `CSS` or `XPath` locators in tests:\n\n```js\n// by name\nI.fillField('user_basic[email]', 'hello@world.com')\n// by CSS\nI.fillField('#user_basic_email', 'hello@world.com')\n// don't make us guess locator type, specify it\nI.fillField({ css: '#user_basic_email' }, 'hello@world.com')\n```\n\nOther methods like `checkOption`, and `click` work in a similar manner. They can take labels or CSS or XPath locators to find elements to interact.\n\n### Assertions\n\nAssertions start with `see` or `dontSee` prefix. In our case we are asserting that string 'User is valid' is somewhere in a webpage.\nHowever, we can narrow the search to particular element by providing a second parameter:\n\n```js\nI.see('User is valid')\n// better to specify context:\nI.see('User is valid', '.alert-success')\n```\n\nIn this case 'User is valid' string will be searched only inside elements located by CSS `.alert-success`.\n\n### Grabbers\n\nIn case you need to return a value from a webpage and use it directly in test, you should use methods with `grab` prefix.\nThey are expected to be used inside `async/await` functions, and their results will be available in test:\n\n```js\nFeature('CodeceptJS Demonstration')\n\nScenario('test page title', async ({ I }) =\u003e {\n  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation')\n  const title = await I.grabTitle()\n  I.expectEqual(title, 'Example application with SimpleForm and Twitter Bootstrap') // Avaiable with Expect helper. -\u003e https://codecept.io/helpers/Expect/\n})\n```\n\nThe same way you can grab text, attributes, or form values and use them in next test steps.\n\n### Before/After\n\nCommon preparation steps like opening a web page, logging in a user, can be placed in `Before` or `Background`:\n\n```js\nconst { I } = inject()\n\nFeature('CodeceptJS Demonstration')\n\nBefore(() =\u003e {\n  // or Background\n  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation')\n})\n\nScenario('test some forms', () =\u003e {\n  I.click('Create User')\n  I.see('User is valid')\n  I.dontSeeInCurrentUrl('/documentation')\n})\n\nScenario('test title', () =\u003e {\n  I.seeInTitle('Example application')\n})\n```\n\n## HTML Reporter\n\nCodeceptJS includes a powerful built-in HTML Reporter that generates comprehensive, interactive test reports with detailed information about your test runs. The HTML reporter is **enabled by default** for all new projects and provides:\n\n### Features\n\n- **Interactive Dashboard**: Visual statistics, pie charts, and expandable test details\n- **Step-by-Step Execution**: Shows individual test steps with timing and status indicators\n- **BDD/Gherkin Support**: Full support for feature files with proper scenario formatting\n- **System Information**: Comprehensive environment details including browser versions\n- **Advanced Filtering**: Real-time filtering by status, tags, features, and test types\n- **History Tracking**: Multi-run history with trend visualization\n- **Error Details**: Clean formatting of error messages and stack traces\n- **Artifacts Support**: Display screenshots and other test artifacts\n\n### Visual Examples\n\n#### Interactive Test Dashboard\n\nThe main dashboard provides a complete overview with interactive statistics and pie charts:\n\n![HTML Reporter Dashboard](docs/shared/html-reporter-main-dashboard.png)\n\n#### Detailed Test Results\n\nEach test shows comprehensive execution details with expandable step information:\n\n![HTML Reporter Test Details](docs/shared/html-reporter-test-details.png)\n\n#### Advanced Filtering Capabilities\n\nReal-time filtering allows quick navigation through test results:\n\n![HTML Reporter Filtering](docs/shared/html-reporter-filtering.png)\n\n#### BDD/Gherkin Support\n\nFull support for Gherkin scenarios with proper feature formatting:\n\n![HTML Reporter BDD Details](docs/shared/html-reporter-bdd-details.png)\n\nThe HTML reporter generates self-contained reports that can be easily shared with your team. Learn more about configuration and features in the [HTML Reporter documentation](https://codecept.io/plugins/#htmlreporter).\n\n## PageObjects\n\nCodeceptJS provides the most simple way to create and use page objects in your test.\nYou can create one by running\n\n```sh\nnpx codeceptjs generate pageobject\n```\n\nIt will create a page object file for you and add it to the config.\nLet's assume we created one named `docsPage`:\n\n```js\nconst { I } = inject()\n\nmodule.exports = {\n  fields: {\n    email: '#user_basic_email',\n    password: '#user_basic_password',\n  },\n  submitButton: { css: '#new_user_basic input[type=submit]' },\n\n  sendForm(email, password) {\n    I.fillField(this.fields.email, email)\n    I.fillField(this.fields.password, password)\n    I.click(this.submitButton)\n  },\n}\n```\n\nYou can easily inject it to test by providing its name in test arguments:\n\n```js\nFeature('CodeceptJS Demonstration')\n\nBefore(({ I }) =\u003e {\n  // or Background\n  I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation')\n})\n\nScenario('test some forms', ({ I, docsPage }) =\u003e {\n  docsPage.sendForm('hello@world.com', '123456')\n  I.see('User is valid')\n  I.dontSeeInCurrentUrl('/documentation')\n})\n```\n\nWhen using Typescript, replace `module.exports` with `export` for autocompletion.\n\n## Contributing\n\n- ### [Contributing Guide](https://github.com/codeceptjs/CodeceptJS/blob/master/.github/CONTRIBUTING.md)\n- ### [Code of conduct](https://github.com/codeceptjs/CodeceptJS/blob/master/.github/CODE_OF_CONDUCT.md)\n\n## Contributors\n\nThanks to our awesome contributors! 🎉\n\u003ca href=\"https://github.com/codeceptjs/codeceptjs/graphs/contributors\"\u003e\n\u003cimg src=\"https://contrib.rocks/image?repo=codeceptjs/codeceptjs\" /\u003e\n\u003c/a\u003e\n\nMade with [contrib.rocks](https://contrib.rocks).\n\n## License\n\nMIT © [CodeceptJS Team](http://codecept.io)\n\n[npm-image]: https://badge.fury.io/js/codeceptjs.svg\n[npm-url]: https://npmjs.org/package/codeceptjs\n[travis-image]: https://travis-ci.org/Codeception/codeceptjs.svg?branch=master\n[travis-url]: https://travis-ci.org/Codeception/codeceptjs\n[daviddm-image]: https://david-dm.org/Codeception/codeceptjs.svg?theme=shields.io\n[daviddm-url]: https://david-dm.org/Codeception/codeceptjs\n[coveralls-image]: https://coveralls.io/repos/Codeception/codeceptjs/badge.svg\n[coveralls-url]: https://coveralls.io/r/Codeception/codeceptjs\n","funding_links":["https://opencollective.com/codeceptjs"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeceptjs%2Fcodeceptjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeceptjs%2Fcodeceptjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeceptjs%2Fcodeceptjs/lists"}