Merge branch 'codeceptjs:3.x' into patch-3

Author: danielrentz

.github/workflows/appium_Android.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - 3.x
+      - 5228-fix-appium-tests
 
 env:
   CI: true

CHANGELOG.md

@@ -4003,7 +4003,7 @@ This change allows using auto-completion when running a specific test.
 - PageObjects simplified to remove `_init()` extra method. Try updated generators and see [updated guide](https://codecept.io/pageobjects/#pageobject).
 - [Puppeteer] [Multiple sessions](https://codecept.io/acceptance/#multiple-sessions) enabled. Requires Puppeteer >= 1.5
 - [Puppeteer] Stability improvement. Waits for for `load` event on page load. This strategy can be changed in config:
-  - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions)
+  - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.waitforoptions.md)
   - `getPageTimeout` config option to set maximum navigation time in milliseconds. Default is 30 seconds.
   - `waitForNavigation` method added. Explicitly waits for navigation to be finished.
 - [WebDriverIO][Protractor][Puppeteer][Nightmare] **Possible BC** `grabTextFrom` unified. Return a text for single matched element and an array of texts for multiple elements.
@@ -4087,7 +4087,7 @@ Scenario('this test should throw error', I => {
 - Added Chinese translation ("zh-CN" and "zh-TW") by @TechQuery.
 - Fixed running tests from a different folder specified by `-c` option.
 - [Puppeteer] Added support for hash handling in URL by @gavoja.
-- [Puppeteer] Fixed setting viewport size by @gavoja. See [Puppeteer issue](https://github.com/GoogleChrome/puppeteer/issues/1183)
+- [Puppeteer] Fixed setting viewport size by @gavoja. See [Puppeteer issue](https://github.com/puppeteer/puppeteer/issues/1183)
 
 ## 1.1.7
 

docs/changelog.md

@@ -3837,7 +3837,7 @@ This change allows using auto-completion when running a specific test.
 - PageObjects simplified to remove `_init()` extra method. Try updated generators and see [updated guide](https://codecept.io/pageobjects/#pageobject).
 - **[Puppeteer]** [Multiple sessions](https://codecept.io/acceptance/#multiple-sessions) enabled. Requires Puppeteer >= 1.5
 - **[Puppeteer]** Stability improvement. Waits for for `load` event on page load. This strategy can be changed in config:
-  - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions)
+  - `waitForNavigation` config option introduced. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.waitforoptions.md)
   - `getPageTimeout` config option to set maximum navigation time in milliseconds. Default is 30 seconds.
   - `waitForNavigation` method added. Explicitly waits for navigation to be finished.
 - [WebDriverIO][Protractor][Puppeteer][Nightmare] **Possible BC** `grabTextFrom` unified. Return a text for single matched element and an array of texts for multiple elements.
@@ -3921,7 +3921,7 @@ Scenario('this test should throw error', I => {
 - Added Chinese translation ("zh-CN" and "zh-TW") by **[TechQuery](https://github.com/TechQuery)**.
 - Fixed running tests from a different folder specified by `-c` option.
 - **[Puppeteer]** Added support for hash handling in URL by **[gavoja](https://github.com/gavoja)**.
-- **[Puppeteer]** Fixed setting viewport size by **[gavoja](https://github.com/gavoja)**. See [Puppeteer issue](https://github.com/GoogleChrome/puppeteer/issues/1183)
+- **[Puppeteer]** Fixed setting viewport size by **[gavoja](https://github.com/gavoja)**. See [Puppeteer issue](https://github.com/puppeteer/puppeteer/issues/1183)
 
 ## 1.1.7
 

docs/custom-helpers.md

@@ -5,7 +5,7 @@ title: Custom Helpers
 
 # Extending CodeceptJS With Custom Helpers
 
-Helper is the core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them. When `I` object is used in tests it delegates execution of its functions to currently enabled helper classes. 
+Helper is the core concept of CodeceptJS. Helper is a wrapper on top of various libraries providing unified interface around them. When `I` object is used in tests it delegates execution of its functions to currently enabled helper classes.
 
 Use Helpers to introduce low-level API to your tests without polluting test scenarios. Helpers can also be used to share functionality across different project and installed as npm packages.
 
@@ -34,10 +34,9 @@ Helpers are classes inherited from [corresponding abstract class](https://github
 Created helper file should look like this:
 
 ```js
-const Helper = require('@codeceptjs/helper');
+const Helper = require('@codeceptjs/helper')
 
 class MyHelper extends Helper {
-
   // before/after hooks
   _before() {
     // remove if not used
@@ -50,48 +49,43 @@ class MyHelper extends Helper {
   // add custom methods here
   // If you need to access other helpers
   // use: this.helpers['helperName']
-
 }
 
-module.exports = MyHelper;
+module.exports = MyHelper
 ```
 
 When the helper is enabled in config all methods of a helper class are available in `I` object.
 For instance, if we add a new method to helper class:
 
 ```js
-const Helper = require('@codeceptjs/helper');
+const Helper = require('@codeceptjs/helper')
 
 class MyHelper extends Helper {
-
   doAwesomeThings() {
-    console.log('Hello from MyHelpr');
+    console.log('Hello from MyHelpr')
   }
-
 }
 ```
 
 We can call a new method from within `I`:
 
 ```js
-I.doAwesomeThings();
+I.doAwesomeThings()
 ```
 
 > Methods starting with `_` are considered special and won't available in `I` object.
 
-
-Please note, `I` object can't be used helper class. As `I` object delegates its calls to helper classes, you can't make a circular dependency on it. Instead of calling `I` inside a helper, you can get access to other helpers by using `helpers` property of a helper. This allows you to access any other enabled helper by its name. 
+Please note, `I` object can't be used helper class. As `I` object delegates its calls to helper classes, you can't make a circular dependency on it. Instead of calling `I` inside a helper, you can get access to other helpers by using `helpers` property of a helper. This allows you to access any other enabled helper by its name.
 
 For instance, to perform a click with Playwright helper, do it like this:
 
 ```js
 doAwesomeThingsWithPlaywright() {
   const { Playwright } = this.helpers;
-  Playwright.click('Awesome');    
+  Playwright.click('Awesome');
 }
 ```
 
-
 After a custom helper is finished you can update CodeceptJS Type Definitions by running:
 
 ```sh
@@ -185,16 +179,16 @@ constructor(config) {
 Helpers may contain several hooks you can use to handle events of a test.
 Implement corresponding methods to them.
 
-* `_init` - before all tests
-* `_finishTest` - after all tests
-* `_before` - before a test
-* `_after` - after a test
-* `_beforeStep` - before each step
-* `_afterStep` - after each step
-* `_beforeSuite` - before each suite
-* `_afterSuite` - after each suite
-* `_passed` - after a test passed
-* `_failed` - after a test failed
+- `_init` - before all tests
+- `_finishTest` - after all tests
+- `_before` - before a test
+- `_after` - after a test
+- `_beforeStep` - before each step
+- `_afterStep` - after each step
+- `_beforeSuite` - before each suite
+- `_afterSuite` - after each suite
+- `_passed` - after a test passed
+- `_failed` - after a test failed
 
 Each implemented method should return a value as they will be added to global promise chain as well.
 
@@ -225,22 +219,20 @@ Retry rules are available in array `recorder.retries`. The last retry rule can b
 
 With Typescript, just simply replacing `module.exports` with `export` for autocompletion.
 
-
 ## Helper Examples
 
 ### Playwright Example
 
 In this example we take the power of Playwright to change geolocation in our tests:
 
 ```js
-const Helper = require('@codeceptjs/helper');
+const Helper = require('@codeceptjs/helper')
 
 class MyHelper extends Helper {
-
   async setGeoLocation(longitude, latitude) {
-    const { browserContext } = this.helpers.Playwright;
-    await browserContext.setGeolocation({ longitude, latitude });
-    await Playwright.refreshPage();
+    const { browserContext } = this.helpers.Playwright
+    await browserContext.setGeolocation({ longitude, latitude })
+    await Playwright.refreshPage()
   }
 }
 ```
@@ -250,10 +242,10 @@ class MyHelper extends Helper {
 Next example demonstrates how to use WebDriver library to create your own test action. Method `seeAuthentication` will use `browser` instance of WebDriver to get access to cookies. Standard NodeJS assertion library will be used (you can use any).
 
 ```js
-const Helper = require('@codeceptjs/helper');
+const Helper = require('@codeceptjs/helper')
 
 // use any assertion library you like
-const assert = require('assert');
+const assert = require('assert')
 
 class MyHelper extends Helper {
   /**
@@ -262,45 +254,43 @@ class MyHelper extends Helper {
   async seeAuthentication() {
     // access current browser of WebDriver helper
     const { WebDriver } = this.helpers
-    const { browser } = WebDriver;
+    const { browser } = WebDriver
 
     // get all cookies according to https://webdriver.io/api/protocol/cookie.html
     // any helper method should return a value in order to be added to promise chain
-    const res = await browser.cookie();
+    const res = await browser.cookie()
     // get values
-    let cookies = res.value;
+    let cookies = res.value
     for (let k in cookies) {
       // check for a cookie
-      if (cookies[k].name != 'logged_in') continue;
-      assert.equal(cookies[k].value, 'yes');
-      return;
+      if (cookies[k].name != 'logged_in') continue
+      assert.equal(cookies[k].value, 'yes')
+      return
     }
-    assert.fail(cookies, 'logged_in', "Auth cookie not set");
+    assert.fail(cookies, 'logged_in', 'Auth cookie not set')
   }
 }
 
-module.exports = MyHelper;
+module.exports = MyHelper
 ```
 
 ### Puppeteer Example
 
-Puppeteer has [nice and elegant API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md) which you can use inside helpers. Accessing `page` instance via `this.helpers.Puppeteer.page` from inside a helper.
+Puppeteer has [nice and elegant API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/index.md) which you can use inside helpers. Accessing `page` instance via `this.helpers.Puppeteer.page` from inside a helper.
 
-Let's see how we can use [emulate](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageemulateoptions) function to emulate iPhone browser in a test.
+Let's see how we can use [emulate](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.page.emulate.md) function to emulate iPhone browser in a test.
 
 ```js
-const Helper = require('@codeceptjs/helper');
-const puppeteer = require('puppeteer');
-const iPhone = puppeteer.devices['iPhone 6'];
+const Helper = require('@codeceptjs/helper')
+const puppeteer = require('puppeteer')
+const iPhone = puppeteer.devices['iPhone 6']
 
 class MyHelper extends Helper {
-
   async emulateIPhone() {
-    const { page } = this.helpers.Puppeteer;
-    await page.emulate(iPhone);
+    const { page } = this.helpers.Puppeteer
+    await page.emulate(iPhone)
   }
-
 }
 
-module.exports = MyHelper;
+module.exports = MyHelper
 ```

docs/helpers/Playwright.md

@@ -82,6 +82,12 @@ Type: [object][6]
 *   `recordHar` **[object][6]?** record HAR and will be saved to `output/har`. See more of [HAR options][3].
 *   `testIdAttribute` **[string][9]?** locate elements based on the testIdAttribute. See more of [locate by test id][49].
 *   `customLocatorStrategies` **[object][6]?** custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(`[role="${selector}"]`) } }`
+*   `storageState` **([string][9] | [object][6])?** Playwright storage state (path to JSON file or object)
+    passed directly to `browser.newContext`.
+    If a Scenario is declared with a `cookies` option (e.g. `Scenario('name', { cookies: [...] }, fn)`),
+    those cookies are used instead and the configured `storageState` is ignored (no merge).
+    May include session cookies, auth tokens, localStorage and (if captured with
+    `grabStorageState({ indexedDB: true })`) IndexedDB data; treat as sensitive and do not commit.
 
 
 
@@ -1333,6 +1339,28 @@ let pageSource = await I.grabSource();
 
 Returns **[Promise][22]<[string][9]>** source code
 
+### grabStorageState
+
+Grab the current storage state (cookies, localStorage, etc.) via Playwright's `browserContext.storageState()`.
+Returns the raw object that Playwright provides.
+
+Security: The returned object can contain authentication tokens, session cookies
+and (when `indexedDB: true` is used) data that may include user PII. Treat it as a secret.
+Avoid committing it to source control and prefer storing it in a protected secrets store / CI artifact vault.
+
+#### Parameters
+
+*   `options` **[object][6]?**  
+
+    *   `options.indexedDB` **[boolean][26]?** set to true to include IndexedDB in snapshot (Playwright >=1.51)```js
+        // basic usage
+        const state = await I.grabStorageState();
+        require('fs').writeFileSync('authState.json', JSON.stringify(state));
+
+        // include IndexedDB when using Firebase Auth, etc.
+        const stateWithIDB = await I.grabStorageState({ indexedDB: true });
+        ```
+
 ### grabTextFrom
 
 Retrieves a text from an element located by CSS or XPath and returns it to test.
@@ -1575,7 +1603,7 @@ I.openNewTab({ isMobile: true });
 
 ### pressKey
 
-*Note:* Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Puppeteer#1313][33]).
+*Note:* Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313][33]).
 
 Presses a key in the browser (on a focused element).
 
@@ -2774,7 +2802,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 [32]: https://github.com/microsoft/playwright/blob/main/docs/api.md#browsernewpageoptions
 
-[33]: https://github.com/GoogleChrome/puppeteer/issues/1313
+[33]: https://github.com/puppeteer/puppeteer/issues/1313
 
 [34]: #fillfield
 
@@ -2790,7 +2818,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 [40]: https://github.com/microsoft/playwright/blob/main/docs/src/api/class-browser.md
 
-[41]: https://playwright.dev/docs/api/class-page?_highlight=waitfornavi#pagewaitfornavigationoptions
+[41]: https://playwright.dev/docs/api/class-page#page-wait-for-navigation
 
 [42]: https://playwright.dev/docs/api/class-page#page-wait-for-url
 

docs/helpers/Puppeteer.md

@@ -49,15 +49,15 @@ Type: [object][4]
 *   `keepBrowserState` **[boolean][23]?** keep browser state between tests when `restart` is set to false.
 *   `keepCookies` **[boolean][23]?** keep cookies between tests when `restart` is set to false.
 *   `waitForAction` **[number][11]?** how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
-*   `waitForNavigation` **[string][6]?** when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API][26]. Array values are accepted as well.
+*   `waitForNavigation` **([string][6] | [Array][16]<[string][6]>)?** when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API][28]. Array values are accepted as well.
 *   `pressKeyDelay` **[number][11]?** delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
 *   `getPageTimeout` **[number][11]?** config option to set maximum navigation time in milliseconds. If the timeout is set to 0, then timeout will be disabled.
 *   `waitForTimeout` **[number][11]?** default wait* timeout in ms.
 *   `windowSize` **[string][6]?** default window size. Set a dimension in format WIDTHxHEIGHT like `640x480`.
 *   `userAgent` **[string][6]?** user-agent string.
 *   `manualStart` **[boolean][23]?** do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
 *   `browser` **[string][6]?** can be changed to `firefox` when using [puppeteer-firefox][2].
-*   `chrome` **[object][4]?** pass additional [Puppeteer run options][28].
+*   `chrome` **[object][4]?** pass additional [Puppeteer run options][29].
 *   `highlightElement` **[boolean][23]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
 
 ## findElement
@@ -1412,7 +1412,7 @@ I.openNewTab();
 
 ### pressKey
 
-*Note:* Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/puppeteer#1313][20]).
+*Note:* Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313][20]).
 
 Presses a key in the browser (on a focused element).
 
@@ -2501,7 +2501,7 @@ I.waitUrlEquals('http://127.0.0.1:8000/info');
 
 Returns **void** automatically synchronized promise through #recorder
 
-[1]: https://github.com/GoogleChrome/puppeteer
+[1]: https://github.com/puppeteer/puppeteer
 
 [2]: https://codecept.io/helpers/Puppeteer-firefox
 
@@ -2539,7 +2539,7 @@ Returns **void** automatically synchronized promise through #recorder
 
 [19]: https://pptr.dev/guides/network-interception
 
-[20]: https://github.com/GoogleChrome/puppeteer/issues/1313
+[20]: https://github.com/puppeteer/puppeteer/issues/1313
 
 [21]: #fillfield
 
@@ -2551,8 +2551,10 @@ Returns **void** automatically synchronized promise through #recorder
 
 [25]: https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-browser
 
-[26]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions
+[26]: https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.page.waitfornavigation.md
 
 [27]: https://pptr.dev/api/puppeteer.tracing
 
-[28]: https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions
+[28]: https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.waitforoptions.md
+
+[29]: https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.launchoptions.md