codeceptjs 3.4.1 → 3.5.1-2.beta.7

package/docs/reports.md

@@ -1,392 +0,0 @@
----
-permalink: /reports
-title: Reporters
----
-
-# Reporters
-
-## Cli
-
-By default, CodeceptJS provides cli reporter with console output.
-Test names and failures will be printed out on screen.
-
-```sh
-GitHub --
- ✓ search in 2577ms
- ✓ signin in 2170ms
- ✖ register in 1306ms
-
--- FAILURES:
-
-  1) GitHub: register:
-      Field q not found by name|text|CSS|XPath
-
-  Scenario Steps:
-
-  - I.fillField("q", "aaa") at examples/github_test.js:29:7
-  - I.fillField("user[password]", "user@user.com") at examples/github_test.js:28:7
-  - I.fillField("user[email]", "user@user.com") at examples/github_test.js:27:7
-  - I.fillField("user[login]", "User") at examples/github_test.js:26:7
-
-
-
-  Run with --verbose flag to see NodeJS stacktrace
-
-```
-
-output steps use `--steps` option:
-```
-npx codeceptjs run --steps
-```
-
-Output:
-
-```sh
-GitHub --
- search
- • I am on page "https://github.com"
- • I am on page "https://github.com/search"
- • I fill field "Search GitHub", "CodeceptJS"
- • I press key "Enter"
- • I see "Codeception/CodeceptJS", "a"
- ✓ OK in 2681ms
-
- signin
- • I am on page "https://github.com"
- • I click "Sign in"
- • I see "Sign in to GitHub"
- • I fill field "Username or email address", "something@totest.com"
- • I fill field "Password", "123456"
- • I click "Sign in"
- • I see "Incorrect username or password.", ".flash-error"
- ✓ OK in 2252ms
-
- register
- • I am on page "https://github.com"
-   Within .js-signup-form:
-   • I fill field "user[login]", "User"
-   • I fill field "user[email]", "user@user.com"
-   • I fill field "user[password]", "user@user.com"
-   • I fill field "q", "aaa"
- ✖ FAILED in 1260ms
-```
-
-To get additional information about test execution use `--debug` option.
-
-
-```
-npx codeceptjs run --debug
-```
-
-
-This will show execution steps
-as well as notices from test runner. To get even more information with more technical details like error stack traces,
-and global promises, or events use `--verbose` mode.
-
-```
-npx codeceptjs run --verbose
-```
-
-```sh
-GitHub --
- register
-   [1] Starting recording promises
-   Emitted | test.before
- > WebDriver._before
-   [1] Queued | hook WebDriver._before()
-   [1] Queued | amOnPage: https://github.com
-   Emitted | step.before (I am on page "https://github.com")
- • I am on page "https://github.com"
-   Emitted | step.after (I am on page "https://github.com")
-   Emitted | test.start ([object Object])
-...
-```
-
-Please use verbose output when reporting issues to GitHub.
-
-### Dry Run
-
-There is a way to list all tests and their steps without actually executing them. Execute tests in `dry-run` mode to see all available tests:
-
-```
-npx codeceptjs dry-run
-```
-
-Output:
-
-```
-Tests from /home/davert/projects/codeceptjs/examples:
-
-Business rules --
-  ☐ do something
-Google --
-  ☐ test @123
-GitHub -- /home/davert/projects/codeceptjs/examples/github_test.js
-  ☐ Visit Home Page @retry
-  ☐ search @grop
-  ☐ signin @normal @important @slow
-  ☐ signin2
-  ☐ register
-
-  Total: 3 suites | 7 tests
-
---- DRY MODE: No tests were executed ---
-```
-
-Pass `--steps` or `--debug` option as in `run` command to also get steps and substeps to be printed. In this mode **tests will be executed** but all helpers and plugins disabled, so no real actions will be performed.
-
-```
-npx codecepjs dry-run --debug
-```
-
-> ℹ If you use custom JavaScript code inside tests, or rely on values from `grab*` commands, dry-run may produce error output.
-
-
-## Testomat.io
-
-[Testomat.io](https://testomat.io) is a modern test management tool focused on CodeceptJS and **created by CodeceptJS team**.
-Testomat.io is commercial SaaS service that can receive run reports from local runs or CI. Out of box Testomat.io supports parallel runs, uploading of screenshots and videos.
-
-![](https://user-images.githubusercontent.com/220264/151728836-b52d2b2b-56e1-4640-8d3a-b39de817b1fd.png)
-
-> 😻 **Testomat.io is free** for small teams, so you can use its reporting features with CodeceptJS.
-
-To receive run reports you should:
-
-* [Sign up](https://app.testomat.io/users/sign_up) at Testomat.io
-* Create a new "Classical" project (select "BDD" project if you use CodeceptJS in BDD mode)
-* Select "Import from Source Code"
-* Select "CodeceptJS" as testing framework and JavaScript or TypeScript as a language. If you use BDD select "Gherkin" as language.
-* Execute provided command in a terminal with your project. This will be "check-tests" or "check-cucmber" command. It scans all your test files and imports them into Testomat.io. This way all your e2e tests will be visible in one UI.
-* After tests are imported, go to Runs tab and select "Setup automated tests".
-* Follow the instructions:
-
-
-![image](https://user-images.githubusercontent.com/77803888/151834217-5da44d92-a59a-458d-8856-64ce61bf3a38.png)
-
-* You will need to install `@testomatio/reporter` package and enable it as a plugin in codeceptjs config:
-
-```js
-plugins: {
-  testomatio: {
-    enabled: true,
-    require: '@testomatio/reporter/lib/adapter/codecept',
-    apiKey: process.env.TESTOMATIO,
-  }
-}
-```
-
-* Run tests with `TESTOMATIO=` env variable and API key provided by Testomat.io
-* See the run report is created and updated in realtime.
-
-
-[Testomat.io](https://testomat.io) reporter works in the cloud, so it doesn't require you to install additional software. It can be integrated with your CI service to rerun only failed tests, launch new runs from UI, and send report notifications by email or in Slack, MS Teams, or create issue in Jira.
-
-
-
-## ReportPortal
-
-For enterprise grade we reporting we recommend using [ReportPortal](https://reportportal.io).
-
-![](https://camo.githubusercontent.com/6550c0365f1d0ce1e29c53f1860b12957d1fc529/68747470733a2f2f692e6962622e636f2f516d353247306e2f53637265656e73686f742d323031392d30342d31312d61742d31352d35372d34302e706e67)
-
-[ReportPortal](https://reportportal.io) is open-source self-hosted service for aggregating test execution reports.
-Think of it as Kibana but for test reports.
-
-Use official [CodeceptJS Agent for ReportPortal](https://github.com/reportportal/agent-js-codecept/) to start publishing your test results.
-
-
-## XML
-
-Use default xunit reporter of Mocha to print xml reports. Provide `--reporter xunit` to get the report to screen.
-It is recommended to use more powerful [`mocha-junit-reporter`](https://www.npmjs.com/package/mocha-junit-reporter) package
-to get better support for Jenkins CI.
-
-Install it via NPM (locally or globally, depending on CodeceptJS installation type):
-
-```sh
-npm i mocha-junit-reporter
-```
-
-Additional configuration should be added to `codecept.conf.js` to print xml report to `output` directory:
-
-```json
-  "mocha": {
-    "reporterOptions": {
-        "mochaFile": "output/result.xml"
-    }
-  },
-```
-
-Execute CodeceptJS with JUnit reporter:
-
-```sh
-codeceptjs run --reporter mocha-junit-reporter
-```
-
-Result will be located at `output/result.xml` file.
-
-## Html
-
-Best HTML reports could be produced with [mochawesome](https://www.npmjs.com/package/mochawesome) reporter.
-
-![mochawesome](/img/mochawesome.png)
-
-Install it via NPM:
-
-```sh
-npm i mochawesome
-```
-
-If you get an error like this
-```sh
-"mochawesome" reporter not found
-
-invalid reporter "mochawesome"
-```
-
-Make sure to have mocha installed or install it:
-
-```sh
-npm i mocha -D
-```
-
-Configure it to use `output` directory to print HTML reports:
-
-```json
-  "mocha": {
-    "reporterOptions": {
-        "reportDir": "output"
-    }
-  },
-```
-
-Execute CodeceptJS with HTML reporter:
-
-```sh
-codeceptjs run --reporter mochawesome
-```
-
-Result will be located at `output/index.html` file.
-
-### Advanced usage
-
-Want to have screenshots for failed tests?
-Then add Mochawesome helper to your config:
-
-```json
-  "helpers": {
-    "Mochawesome": {
-        "uniqueScreenshotNames": "true"
-    }
-  },
-```
-
-Then tests with failure will have screenshots.
-
-### Configuration
-
-This helper should be configured in codecept.conf.ts
-
-- `uniqueScreenshotNames` (optional, default: false) - option to prevent screenshot override if you have scenarios with the same name in different suites. This option should be the same as in common helper.
-- `disableScreenshots` (optional, default: false)  - don't save screenshot on failure. This option should be the same as in common helper.
-
-Also if you will add Mochawesome helper, then you will able to add custom context in report:
-
-#### addMochawesomeContext
-
-Adds context to executed test in HTML report:
-
-```js
-I.addMochawesomeContext('simple string');
-I.addMochawesomeContext('http://www.url.com/pathname');
-I.addMochawesomeContext('http://www.url.com/screenshot-maybe.jpg');
-I.addMochawesomeContext({title: 'expected output',
-                         value: {
-                           a: 1,
-                           b: '2',
-                           c: 'd'
-                         }
-});
-```
-
-##### Parameters
-
-- `context`  string, url, path to screenshot, object. See [this](https://www.npmjs.com/package/mochawesome#adding-test-context)
-
-## Multi Reports
-
-Want to use several reporters in the same time? Try to use [mocha-multi](https://www.npmjs.com/package/mocha-multi) reporter
-
-Install it via NPM:
-
-```sh
-npm i mocha-multi
-```
-
-Configure mocha-multi with reports that you want:
-
-```json
-  "mocha": {
-    "reporterOptions": {
-      "codeceptjs-cli-reporter": {
-        "stdout": "-",
-        "options": {
-          "verbose": true,
-          "steps": true,
-        }
-      },
-      "mochawesome": {
-        "stdout": "./output/console.log",
-        "options": {
-          "reportDir": "./output",
-          "reportFilename": "report"
-        }
-      },
-      "mocha-junit-reporter": {
-        "stdout": "./output/console.log",
-        "options": {
-          "mochaFile": "./output/result.xml",
-          "attachments": true //add screenshot for a failed test
-        }
-      }
-    }
-  }
-```
-
-Execute CodeceptJS with mocha-multi reporter:
-
-```sh
-npx codeceptjs run --reporter mocha-multi
-```
-
-This will give you cli with steps in console and HTML report in `output` directory.
-
-
-## Testrail
-
-Testrail integration with CodeceptJS is now so seamless. The test run is created automatically afterwards. The screenshots of failed tests are also attached to test results.
-
-Try to use [codeceptjs-testrail](https://www.npmjs.com/package/codeceptjs-testrail) plugin
-
-Install it via NPM:
-
-```sh
-npm i codeceptjs-testrail --save
-```
-
-![Attachemnt for failed case](http://g.recordit.co/ajaa2QRlnW.gif)
-
-Now there is new feature, add the configuration to test run of test plan
-![Attachemnt for failed case](http://g.recordit.co/uQLvQUq7cT.gif)
-
-
-## Tesults
-
-Submit test results data from CodeceptJS to [Tesults](https://www.tesults.com) easily with the [codeceptjs-tesults](https://www.npmjs.com/package/codeceptjs-tesults) plugin. Test results data is submitted automatically after a test run completes.
-
-```sh
-npm i codeceptjs-tesults --save
-```
-
-Once installed, follow the [quick and easy integration instructions](https://www.tesults.com/docs/codeceptjs) to get setup in no time.

package/docs/secrets.md

@@ -1,30 +0,0 @@
-# Secrets
-
-It is possible to **mask out sensitive data** when passing it to steps. This is important when filling password fields, or sending secure keys to API endpoint. 
-
-Wrap data in `secret` function to mask sensitive values in output and logs.
-
-For basic string `secret` just wrap a value into a string:
-
-```js
-I.fillField('password', secret('123456'));
-```
-
-When executed it will be printed like this:
-
-```
-I fill field "password" "*****"
-```
-
-For an object, which can be a payload to POST request, specify which fields should be masked:
-
-```js
-I.sendPostRequest('/login', secret({
-  name: 'davert',
-  password: '123456'
-}, 'password'))
-```
-
-The object created from `secret` is as Proxy to the object passed in. When printed password will be replaced with ****. 
-
-> ⚠️ Only direct properties of the object can be masked via `secret`

package/docs/shadow.md

@@ -1,68 +0,0 @@
----
-permalink: /shadow
-title: Locating Shadow Dom Elements
----
-
-# Locating Shadow Dom Elements
-
-> ℹ Shadow DOM locators is supported only in WebDriver helper
-
-Shadow DOM is one of the key browser features that make up web components. Web components are a really great way to build reusable elements, and are able to scale all the way up to complete web applications. Style encapsulation, the feature that gives shadow DOM it's power, has been a bit of a pain when it comes to E2E or UI testing. Things just got a little easier though, as CodeceptJS introduced built-in support for shadow DOM via locators of type `shadow`. Let's dig into what they're all about.
-
-Generated HTML code may often look like this (ref: [Salesforce's Lighting Web Components](https://github.com/salesforce/lwc)):
-
-```js
-<body>
-  <my-app>
-    <recipe-hello>
-      <button>Click Me!</button>
-    </recipe-hello>
-    <recipe-hello-binding>
-      <ui-input>
-        <input type="text" class="input">
-      </ui-input>
-    </recipe-hello-binding>
-  </my-app>
-</body>
-```
-
-This uses custom elements, `my-app`, `recipe-hello`, `recipe-hello-binding` and `ui-input`. It's quite common that clickable elements are not actual `a` or `button` elements but custom elements. This way `I.click('Click Me!');` won't work, as well as `fillField('.input', 'value)`. Finding a correct locator for such cases turns to be almost impossible until `shadow` element support is added to CodeceptJS.
-
-## Locate Shadow Dom
-
-For Web Components or [Salesforce's Lighting Web Components](https://github.com/salesforce/lwc) with Shadow DOM's, a special `shadow` locator is available. It allows to select an element by its shadow dom sequences and sequences are defined as an Array of `elements`. Elements defined in the array of `elements` must be in the ordered the shadow elements appear in the DOM.
-
-```js
-{ shadow: ['my-app', 'recipe-hello', 'button'] }
-{ shadow: ['my-app', 'recipe-hello-binding', 'ui-input', 'input.input'] }
-```
-
-In WebDriver, you can use shadow locators in any method where locator is required.
-
-For example, to fill value in `input` field or to click the `Click Me!` button, in above HTML code:
-
-```js
-I.fillField({ shadow: ['my-app', 'recipe-hello-binding', 'ui-input', 'input.input'] }, 'value');
-I.click({ shadow: ['my-app', 'recipe-hello', 'button'] });
-```
-
-## Example
-
-```js
-Feature('Shadow Dom Locators');
-
-Scenario('should fill input field within shadow elements', ({I}) => {
-
-  // navigate to LWC webpage containing shadow dom
-  I.amOnPage('https://recipes.lwc.dev/');
-
-  // click Click Me! button
-  I.click({ shadow: ['my-app', 'recipe-hello', 'button'] });
-
-  // fill the input field
-  I.fillField({ shadow: ['my-app', 'recipe-hello-binding', 'ui-input', 'input.input'] }, 'value');
-
-});
-
-
-```

package/docs/shared/keys.mustache

@@ -1,31 +0,0 @@
-[Valid key names](https://w3c.github.io/webdriver/#keyboard-actions) are:
-
-- `'Add'`,
-- `'Alt'`,
-- `'ArrowDown'` or `'Down arrow'`,
-- `'ArrowLeft'` or `'Left arrow'`,
-- `'ArrowRight'` or `'Right arrow'`,
-- `'ArrowUp'` or `'Up arrow'`,
-- `'Backspace'`,
-- `'Command'`,
-- `'Control'`,
-- `'Del'`,
-- `'Divide'`,
-- `'End'`,
-- `'Enter'`,
-- `'Equals'`,
-- `'Escape'`,
-- `'F1 to F12'`,
-- `'Home'`,
-- `'Insert'`,
-- `'Meta'`,
-- `'Multiply'`,
-- `'Numpad 0'` to `'Numpad 9'`,
-- `'Pagedown'` or `'PageDown'`,
-- `'Pageup'` or `'PageUp'`,
-- `'Pause'`,
-- `'Semicolon'`,
-- `'Shift'`,
-- `'Space'`,
-- `'Subtract'`,
-- `'Tab'`.

package/docs/shared/react.mustache

@@ -1 +0,0 @@
-This action supports [React locators](https://codecept.io/react#locators)

package/docs/testcafe.md

@@ -1,174 +0,0 @@
----
-permalink: /testcafe
-title: Testing with TestCafe
----
-
-# Testing with TestCafe
-
-[TestCafe](https://devexpress.github.io/testcafe/) is another alternative engine for driving browsers. It is driven by unique technology which provides fast and simple cross browser testing for desktop and mobile browsers. Unlike WebDriver or Puppeteer, TestCafe doesn't control a browser at all. It is not a browser itself, like [Nightmare](/nightmare) or Cypress. **TestCafe core is a proxy server** that runs behind the scene, and transforms all HTML and JS to include code that is needed for test automation.
-
-![Testcafe](/img/testcafe.png)
-
-This is very smart idea. But to use TestCafe on daily basis you need to clearly understand its benefits and limitations:
-
-### Pros
-
-* **Fast**. Browser is controlled from inside a web page. This makes test run inside a browser as fast as your browser can render page with no extra network requests.
-* **Simple Cross-Browser Support.** Because TestCafe only launches browsers, it can **automate browser** on desktop or mobile. Unlike WebDriver, you don't need special version of browser and driver to prepare to run tests. Setup simplified. All you need is just a browser installed, and you are ready to go.
-* **Stable to Execution.** Because a test is executed inside a browser, the network latency effects are reduced. Unlike WebDriver you won't hit stale element exceptions, or element not interactable exceptions, as from within a web browser all DOM elements are accessible.
-
-## Cons
-
-* **Magic.** Browsers executed in TestCafe are not aware that they run in test mode. So at some edges automation control can be broken. It's also quite hard to debug possible issues, as you don't know how actually a web page is parsed to inject automation scripts.
-* **No Browser Control.** Because TestCafe do not control browser, you can't actually automate all users actions. For instance, TestCafe can't open new tabs or open a new browser window in incognito mode. There can be also some issues running tests on 3rd party servers or inside iframes.
-* **Simulated Events.** Events like `click` or `doubleClick` are simulated by JavaScript internally. Inside WebDriver or Puppeteer, where those events are dispatched by a browser, called native events. Native events are closer to real user experience. So in some cases simulated events wouldn't represent actual user experience, which can lead to false positive results. For instance, a button which can't be physically clicked by a user, would be clickable inside TestCafe.
-
-Anyway, TestCafe is a good option to start if you need cross browser testing. And here is the **reason to use TestCafe with CodeceptJS: if you hit an edge case or issue, you can easily switch your tests to WebDriver**. As all helpers in CodeceptJS share the same syntax.
-
-CodeceptJS is a rich testing frameworks which also provides features missing in original TestCafe:
-
-* [Cucumber integration](/bdd)
-* [Real Page Objects](/pageobjects)
-* [Data Management via API](/data)
-* and others
-
-## Writing Tests
-
-To start using TestCafe with CodeceptJS install both via NPM
-
-> If you don't have `package.json` in your project, create it with `npm init -y`.
-
-```
-npm i codeceptjs testcafe --save-dev
-```
-
-Then you need to initialize a project, selecting TestCafe when asked:
-
-```
-npx codeceptjs init
-```
-
-A first test should be created with `codeceptjs gt` command
-
-```
-npx codeceptjs gt
-```
-
-In the next example we will [TodoMVC application](https://todomvc.com/examples/angularjs/#/). So let's create a test which will fill in todo list:
-
-```js
-Feature('TodoMVC');
-
-Scenario('create todo item', ({ I }) => {
-  I.amOnPage('http://todomvc.com/examples/angularjs/#/');
-  I.fillField('.new-todo', todo)
-  I.pressKey('Enter');
-  I.seeNumberOfVisibleElements('.todo-list li', 1);
-  I.see('1 item left', '.todo-count');
-});
-```
-
-Same syntax is the same for all helpers in CodeceptJS so to learn more about available commands learn [CodeceptJS Basics](/basics).
-
-> [▶ Complete list of TestCafe actions](/helpers/TestCafe)
-
-## Page Objects
-
-Multiple tests can be refactored to share some logic and locators. It is recommended to use PageObjects for this. For instance, in example above, we could create special actions for creating todos and checking them. If we move such methods in a corresponding object a test would look even clearer:
-
-```js
-Scenario('Create a new todo item', async ({ I, TodosPage }) => {
-  I.say('Given I have an empty todo list')
-
-  I.say('When I create a todo "foo"')
-  TodosPage.enterTodo('foo')
-
-  I.say('Then I see the new todo on my list')
-  TodosPage.seeNumberOfTodos(1)
-
-  I.saveScreenshot('create-todo-item.png')
-})
-
-Scenario('Create multiple todo items', async ({ I, TodosPage }) => {
-  I.say('Given I have an empty todo list')
-
-  I.say('When I create todos "foo", "bar" and "baz"')
-  TodosPage.enterTodo('foo')
-  TodosPage.enterTodo('bar')
-  TodosPage.enterTodo('baz')
-
-  I.say('Then I have these 3 todos on my list')
-  TodosPage.seeNumberOfTodos(3)
-
-  I.saveScreenshot('create-multiple-todo-items.png')
-})
-```
-
-> ℹ [Source code of this example](https://github.com/hubidu/codeceptjs-testcafe-todomvc) is available on GitHub.
-
-A PageObject can be injected into a test by its name. Here is how TodosPage looks like:
-
-```js
-// inside todos_page.js
-const { I } = inject();
-
-module.exports = {
-    goto() {
-        I.amOnPage('http://todomvc.com/examples/angularjs/#/')
-    },
-
-    enterTodo(todo) {
-        I.fillField('.new-todo', todo)
-        I.pressKey('Enter')
-    },
-
-    seeNumberOfTodos(numberOfTodos) {
-        I.seeNumberOfVisibleElements('.todo-list li', numberOfTodos)
-    },
-}
-```
-
-> [▶ Read more about PageObjects in CodeceptJS](/pageobjects)
-
-
-## Accessing TestCafe API
-
-To get [testController](https://devexpress.github.io/testcafe/documentation/test-api/test-code-structure.html#test-controller))) inside a test use [`I.useTestCafeTo`](/helpers/TestCafe/#usetestcafeto) method with a callback.
-To keep test readable provide a description of a callback inside the first parameter.
-
-```js
-I.useTestCafeTo('do some things using native webdriverio api', async ({ t }) => {
-  await t.click() // use testcafe api here
-});
-```
-
-Because all TestCafe commands are asynchronous a callback function must be async.
-
-
-## Extending
-
-If you want to use TestCafe API inside your tests you can put them into actions of `I` object. To do so you can generate a new helper, access TestCafe helper, and get the test controller.
-
-Create a helper using `codecepjs gh` command.
-
-```
-npx codeceptjs gh
-```
-
-All methods of newly created class will be added to `I` object.
-
-```js
-const Helper = codeceptjs.helper;
-
-class MyTestCafe extends Helper {
-
-  slowlyFillField(field, text) {
-    // import test controller from TestCafe helper
-    const { t } = this.helpers.TestCafe;
-    // use TestCafe API here
-    return t.setTestSpeed(0.1)
-        .typeText(field, text);
-  }
-
-}
-```