codeceptjs 3.0.6 → 3.1.2

package/docs/helpers/Puppeteer.md

@@ -101,6 +101,8 @@ This helper should be configured in codecept.json or codecept.conf.js
 }
 ```
 
+> Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
+
 #### Example #5: Target URL with provided basic authentication
 
 ```js
@@ -115,7 +117,21 @@ This helper should be configured in codecept.json or codecept.conf.js
 }
 ```
 
-Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
+#### Troubleshooting
+
+Error Message:  `No usable sandbox!`
+
+When running Puppeteer on CI try to disable sandbox if you see that message
+
+    helpers: {
+     Puppeteer: {
+        url: 'http://localhost',
+        show: false,
+        chrome: {
+          args: ['--no-sandbox', '--disable-setuid-sandbox']
+        }
+      },
+    }
 
 ## Access From Helpers
 

package/docs/helpers/REST.md

@@ -61,6 +61,8 @@ Executes axios request
 
 -   `request` **any** 
 
+Returns **[Promise][2]<any>** response
+
 ### _url
 
 Generates url based on format sent (takes endpoint + url if latter lacks 'http')
@@ -80,7 +82,9 @@ I.sendDeleteRequest('/api/users/1');
 #### Parameters
 
 -   `url` **any** 
--   `headers` **[object][2]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+
+Returns **[Promise][2]<any>** response
 
 ### sendGetRequest
 
@@ -93,7 +97,9 @@ I.sendGetRequest('/api/users.json');
 #### Parameters
 
 -   `url` **any** 
--   `headers` **[object][2]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+
+Returns **[Promise][2]<any>** response
 
 ### sendPatchRequest
 
@@ -108,9 +114,11 @@ I.sendPatchRequest('/api/users.json', secret({ "email": "user@user.com" }));
 
 #### Parameters
 
--   `url` **[string][3]** 
+-   `url` **[string][4]** 
 -   `payload` **any** the payload to be sent. By default it is sent as an empty object 
--   `headers` **[object][2]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+
+Returns **[Promise][2]<any>** response
 
 ### sendPostRequest
 
@@ -127,7 +135,9 @@ I.sendPostRequest('/api/users.json', secret({ "email": "user@user.com" }));
 
 -   `url` **any** 
 -   `payload` **any** the payload to be sent. By default it is sent as an empty object 
--   `headers` **[object][2]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+
+Returns **[Promise][2]<any>** response
 
 ### sendPutRequest
 
@@ -142,9 +152,11 @@ I.sendPutRequest('/api/users.json', secret({ "email": "user@user.com" }));
 
 #### Parameters
 
--   `url` **[string][3]** 
+-   `url` **[string][4]** 
 -   `payload` **any** the payload to be sent. By default it is sent as an empty object 
--   `headers` **[object][2]** the headers object to be sent. By default it is sent as an empty object 
+-   `headers` **[object][3]** the headers object to be sent. By default it is sent as an empty object 
+
+Returns **[Promise][2]<any>** response
 
 ### setRequestTimeout
 
@@ -160,6 +172,8 @@ I.setRequestTimeout(10000); // In milliseconds
 
 [1]: https://github.com/axios/axios
 
-[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
-[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

package/docs/helpers/WebDriver.md

@@ -873,6 +873,7 @@ I.fillField({css: 'form#login input[name=username]'}, 'John');
 
 This action supports [React locators](https://codecept.io/react#locators)
 
+    {{ custom }}
 
 ### forceClick
 
@@ -962,7 +963,7 @@ let hint = await I.grabAttributeFrom('#tooltip', 'title');
 -   `locator` **([string][19] | [object][18])** element located by CSS|XPath|strict locator.
 -   `attr` **[string][19]** attribute name.
 
-Returns **[Promise][25]<[string][19]>** attribute valueAppium: can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
+Returns **[Promise][25]<[string][19]>** attribute value
 
 ### grabAttributeFromAll
 
@@ -978,7 +979,7 @@ let hints = await I.grabAttributeFromAll('.tooltip', 'title');
 -   `locator` **([string][19] | [object][18])** element located by CSS|XPath|strict locator.
 -   `attr` **[string][19]** attribute name.
 
-Returns **[Promise][25]<[Array][27]<[string][19]>>** attribute valueAppium: can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
+Returns **[Promise][25]<[Array][27]<[string][19]>>** attribute value
 
 ### grabBrowserLogs
 

package/docs/locators.md

@@ -297,8 +297,35 @@ codeceptjs.locator.addFilter((providedLocator, locatorObj) => {
 ```
 New locator strategy is ready to use:
 
+
 ```js
 I.click('=Login');
 ```
 
+#### Custom Strategy Locators
+
+CodeceptJS provides the option to specify custom locators that uses Custom Locator Strategies defined in the WebDriver configuration. It uses the WebDriverIO's [custom$](https://webdriver.io/docs/api/browser/custom$.html) locators internally to locate the elements on page.
+To use the defined Custom Locator Strategy add your custom strategy to your configuration.
+
+```js
+// in codecept.conf.js
+
+const myStrat = (selector) => {
+  return document.querySelectorAll(selector)
+}
+
+// under WebDriver Helpers Configuration
+WebDriver: {
+  ...
+  customLocatorStrategies: {
+    custom: myStrat
+  }
+}
+```
+
+```js
+I.click({custom: 'my-shadow-element-unique-css'})
+```
+
+
 > For more details on locator object see [Locator](https://github.com/codeceptjs/CodeceptJS/blob/master/lib/locator.js) class implementation.

package/docs/mobile.md

@@ -114,7 +114,7 @@ If you wish to use BrowserStack's [Automated Mobile App Testing](https://www.bro
 
 ```js
 helpers: {
-  Appium:
+  Appium: {
     app: "bs://<hashed app-id>",
     host: "hub-cloud.browserstack.com",
     port: 4444,
@@ -122,6 +122,7 @@ helpers: {
     user: "BROWSERSTACK_USER",
     key: "BROWSERSTACK_KEY",
     device: "iPhone 7"
+  }
 }
 ```
 Here is the full list of [capabilities](https://www.browserstack.com/app-automate/capabilities).

package/docs/nightmare.md

@@ -221,8 +221,3 @@ I.seeAttributeContains('#main img', 'src', '/cat.jpg');
 This sample assertion used `_locate` helper method which searched for elements
 by CSS/XPath or a strict locator. Then `browser.evaluate` method was called to
 use locate found elements on a page and return attribute from the first of them.
-
-## Additional Links
-
-* [Nightmare Tutorial](http://codenroll.it/acceptance-testing-with-codecept-js/) by jploskonka.
-

package/docs/parallel.md

@@ -26,7 +26,7 @@ This command is similar to `run`, however, steps output can't be shown in worker
 
 Each worker spins an instance of CodeceptJS, executes a group of tests, and sends back report to the main process.
 
-By default the tests are assigned one by one to the avaible workers this may lead to multiple execution of `BeforeSuite()`. Use the option `--suites` to assigne the suites one by one to the workers.
+By default the tests are assigned one by one to the available workers this may lead to multiple execution of `BeforeSuite()`. Use the option `--suites` to assigne the suites one by one to the workers.
 
 ```sh
 npx codeceptjs run-workers --suites 2
@@ -196,22 +196,23 @@ workers.on(event.all.result, (status, completedTests, workerStats) => {
 
 ## Sharing Data Between Workers
 
-NodeJS Workers can communicate between each other via messaging system. It may happen that you want to pass some data from one of workers to other. For instance, you may want to share user credentials accross all tests. Data will be appended to a container.
+NodeJS Workers can communicate between each other via messaging system. It may happen that you want to pass some data from one of the workers to other. For instance, you may want to share user credentials accross all tests. Data will be appended to a container.
 
-However, you can't access uninitialized data from a container, so to start, you need to initialized data first. Inside `bootstrap` function of the config we execute the `share` function with `local: true` to initialize value locally:
+However, you can't access uninitialized data from a container, so to start, you need to initialize data first. Inside `bootstrap` function of the config we execute the `share` to initialize value:
 
 
 ```js
 // inside codecept.conf.js
 exports.config = {
   bootstrap() {
-    // append empty userData to container for current worker
-    share({ userData: false }, { local: true });
+    // append empty userData to container
+    share({ userData: false });
   }
 }
 ```
+
 Now each worker has `userData` inside a container. However, it is empty.
-When you obtain real data in one of tests you can this data accross tests. Use `inject` function to access data inside a container:
+When you obtain real data in one of the tests you can now `share` this data accross tests. Use `inject` function to access data inside a container:
 
 ```js
 // get current value of userData
@@ -220,6 +221,12 @@ let { userData } = inject();
 if (!userData) {
   userData = { name: 'user', password: '123456' };
   // now new userData will be shared accross all workers
-  share(userData);
+  share({userData : userData});
 }
 ```
+
+If you want to share data only within same worker, and not across all workers, you need to add option `local: true` every time you run `share` 
+
+```js
+share({ userData: false }, {local: true });
+```

package/docs/playwright.md

@@ -3,11 +3,11 @@ permalink: /playwright
 title: Testing with Playwright
 ---
 
-# Testing with Playwright <Badge text="Since 2.5" type="warning"/>
+# Testing with Playwright
 
 Playwright is a Node library to automate the [Chromium](https://www.chromium.org/Home), [WebKit](https://webkit.org/) and [Firefox](https://www.mozilla.org/en-US/firefox/new/) browsers as well as [Electron](https://www.electronjs.org/) apps with a single API. It enables **cross-browser** web automation that is **ever-green**, **capable**, **reliable** and **fast**.
 
-Playwright was built similarly to [Puppeteer](https://github.com/puppeteer/puppeteer), using its API and so is very different in usage. However, Playwright has cross browser support with better design for test automaiton.
+Playwright was built similarly to [Puppeteer](https://github.com/puppeteer/puppeteer), using its API and so is very different in usage. However, Playwright has cross browser support with better design for test automation.
 
 Take a look at a sample test:
 
@@ -270,7 +270,7 @@ Playwright can emulate browsers of mobile devices. Instead of paying for expensi
 
 Device emulation can be enabled in CodeceptJS globally in a config or per session.
 
-Playwright contains a [list of predefined devices](https://github.com/Microsoft/playwright/blob/master/src/deviceDescriptors.ts) to emulate, for instance this is how you can enable iPhone 6 emulation for all tests:
+Playwright contains a [list of predefined devices](https://github.com/microsoft/playwright/blob/master/src/server/deviceDescriptors.js) to emulate, for instance this is how you can enable iPhone 6 emulation for all tests:
 
 ```js
 const { devices } = require('playwright');
@@ -282,7 +282,7 @@ helpers: {
   }
 }
 ```
-To adjust browser settings you can pass [custom options](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsernewcontextoptions)
+To adjust browser settings you can pass [custom options](https://github.com/microsoft/playwright/blob/master/docs/src/api/class-browsercontext.md)
 
 ```js
 helpers: {
@@ -322,30 +322,197 @@ Playwright can be added to GitHub Actions using [official action](https://github
 
 ## Accessing Playwright API
 
-To get [Playwright API](https://github.com/microsoft/playwright/blob/master/docs/api.md) inside a test use `I.usePlaywrightTo` method with a callback.
+To get [Playwright API](https://playwright.dev/docs/api/class-playwright) inside a test use `I.usePlaywrightTo` method with a callback.
+
+`usePlaywrightTo` passes in an instance of Playwright helper from which you can obtain access to main Playwright classes:
+
+* [`browser`](https://playwright.dev/docs/api/class-browser)
+* [`browserContext`](https://playwright.dev/docs/api/class-browsercontext)
+* [`page`](https://playwright.dev/docs/api/class-page)
+
 To keep test readable provide a description of a callback inside the first parameter.
 
 ```js
-I.usePlaywrightTo('emulate offline mode', async ({ browser, context, page }) => {
+I.usePlaywrightTo('emulate offline mode', async ({ browser, browserContext, page }) => {
   // use browser, page, context objects inside this function
-  await context.setOffline(true);
+  await browserContext.setOffline(true);
 });
 ```
 
 Playwright commands are asynchronous so a callback function must be async.
 
-A Playwright helper is passed as argument for callback, so you can combine Playwrigth API with CodeceptJS API:
+A Playwright helper is passed as argument for callback, so you can combine Playwright API with CodeceptJS API:
 
 ```js
 I.usePlaywrightTo('emulate offline mode', async (Playwright) => {
   // access internal objects browser, page, context of helper
-  await Playwright.context.setOffline(true);
+  await Playwright.browserContext.setOffline(true);
   // call a method of helper, await is required here
   await Playwright.click('Reload');
 });
 
 ```
 
+## Mocking Network Requests <Badge text="Since 3.1" type="warning"/>
+
+Network requests & responses can be mocked and modified. Use `mockRequest` which strictly follows [Playwright's `route` API](https://playwright.dev/docs/api/class-browsercontext#browser-context-route).
+
+```js
+I.mockRoute('/api/**', route => {
+  if (route.request().postData().includes('my-string'))
+    route.fulfill({ body: 'mocked-data' });
+  else
+    route.continue();
+});
+
+I.mockRoute('**/*.{png,jpg,jpeg}', route => route.abort());
+
+// To disable mocking for a route call `stopMockingRoute`
+// for previously mocked URL
+I.stopMockingRoute('**/*.{png,jpg,jpeg}'
+```
+
+To master request intercepting [use `route` object](https://playwright.dev/docs/api/class-route) object passed into mock request handler.
+
+## Video <Badge text="Since 3.1" type="warning"/>
+
+Playwright may record videos for failed tests. This can be enabled in a config with `video: true` option:
+
+```js
+exports.config = {
+  helpers: {
+    Playwright: {
+      // ...
+      video: true
+    }
+  }
+}
+```
+When a test fails and video was enabled a video file is shown under the `artifacts` section in the error message:
+
+```
+-- FAILURES:
+
+  1) GitHub
+       open:
+    
+  Scenario Steps:
+  - I.amOnPage("https://gothub11.com/search") at Test.<anonymous> (./github_test.js:16:5)
+  
+  Artifacts:
+  - screenshot: /home/davert/projects/codeceptjs/examples/output/open.failed.png
+  - video: /home/davert/projects/codeceptjs/examples/output/videos/5ecf6aaa78865bce14d271b55de964fd.webm
+```
+
+Open video and use it to debug a failed test case. Video helps when running tests on CI. Configure your CI system to enable artifacts storage for `output/video` and review videos of failed test case to understand failures. 
+
+## Trace <Badge text="Since 3.1" type="warning"/>
+
+If video is not enough to descover why a test failed a [trace](https://playwright.dev/docs/trace-viewer/) can be recorded.
+
+![](https://user-images.githubusercontent.com/220264/128403246-7e1b9b33-9ce2-42d5-b87b-b8749d5d7a78.png)
+
+Inside a trace you get screenshots, DOM snapshots, console logs, network requests and playwright commands logged and showed on a timeline. This may help for a deep debug of a failed test cases. Trace file is saved into ZIP archive and can be viewed with Trace Viewer built into Playwright.
+
+
+Enable trace with `trace: true` option in a config:
+
+```js
+exports.config = {
+  helpers: {
+    Playwright: {
+      // ...
+      trace: true
+    }
+  }
+}
+```
+
+When a test fails and trace was enabled, a trace file is shown under the `artifacts` section in the error message:
+
+```
+-- FAILURES:
+
+  1) GitHub
+       open:
+    
+  Scenario Steps:
+  - I.amOnPage("https://gothub11.com/search") at Test.<anonymous> (./github_test.js:16:5)
+  
+  Artifacts:
+  - screenshot: /home/davert/projects/codeceptjs/examples/output/open.failed.png
+  - trace: /home/davert/projects/codeceptjs/examples/output/trace/open.zip
+```
+
+Use Playwright's trace viewer to analyze the trace:
+
+```
+npx playwright show-trace {path-to-trace-file}
+```
+
+For instance, this is how you can read a trace for a failed test from an example:
+
+```
+npx playwright show-trace /home/davert/projects/codeceptjs/examples/output/trace/open.zip
+```
+
+## Capturing code coverage
+
+Code coverage can be captured, by enabling the `coverage` plugin in `codecept.config.js`.
+
+```js
+{
+  plugins: {
+    coverage: {
+      enabled: true
+    }
+  }
+}
+```
+
+Once all the tests are completed, `codecept` will create and store coverage in `output/coverage` folder, as shown below.
+
+![](https://user-images.githubusercontent.com/16587779/131362352-30ee9c51-705f-4098-b665-53035ea9275f.png)
+
+### Converting `playwright` coverage to `istanbul` coverage
+
+To convert coverage generated from `playwright` to `istanbul` coverage, you first need to install
+- [`v8-to-istanbul`](https://www.npmjs.com/package/v8-to-istanbul)
+
+Once installed, convert the coverage to a format which `istanbul` can recognize, by writing a script as shown below.
+
+```js
+const v8toIstanbul = require('v8-to-istanbul');
+// read all the coverage file from output/coverage folder
+const coverage = require('./output/coverage/Visit_Home_1630335005.coverage.json');
+const fs = require('fs/promises');
+
+(async () => {
+    for (const entry of coverage) {
+        // Used to get file name
+        const file = entry.url.match(/(?:http(s)*:\/\/.*\/)(?<file>.*)/);
+        const converter = new v8toIstanbul(file.groups.file, 0, {
+            source: entry.source
+        });
+
+        await converter.load();
+        converter.applyCoverage(entry.functions);
+
+        // Store converted coverage file which can later be used to generate report
+        await fs.writeFile('./coverage/final.json', JSON.stringify(converter.toIstanbul(), null, 2));
+    }
+})();
+```
+
+Once the istanbul compatible coverage is generated, use [`nyc`](https://www.npmjs.com/package/nyc) to generate your coverage report in your desired format.
+
+```
+npx nyc report --reporter text -t coverage
+```
+
+The above command will generate a text report like shown below.
+
+![](https://user-images.githubusercontent.com/16587779/131363170-b03b4398-5e9a-4142-bc32-764a5f4a5e11.png)
 ## Extending Helper
 
 To create custom `I.*` commands using Playwright API you need to create a custom helper.
@@ -385,6 +552,6 @@ async setPermissions() {
 }
 ```
 
-> [▶ Learn more about BrowserContext](https://github.com/microsoft/playwright/blob/master/docs/api.md#class-browsercontext)
+> [▶ Learn more about BrowserContext](https://github.com/microsoft/playwright/blob/master/docs/src/api/class-browsercontext.md)
 
-> [▶ Learn more about Helpers](http://codecept.io/helpers/)
+> [▶ Learn more about Helpers](https://codecept.io/helpers/)