From 9de8e6db80800dc7f6fd098214ced23bc8bb5dea Mon Sep 17 00:00:00 2001 From: Daniel Rentz Date: Tue, 30 Sep 2025 17:30:35 +0200 Subject: [PATCH 1/4] fixed: types: PupeteerConfig.waitForNavigation can be an array --- docs/helpers/Puppeteer.md | 1109 +++++++++++++++++-------------------- lib/helper/Puppeteer.js | 2 +- 2 files changed, 507 insertions(+), 604 deletions(-) diff --git a/docs/helpers/Puppeteer.md b/docs/helpers/Puppeteer.md index 98c658b11..083758e90 100644 --- a/docs/helpers/Puppeteer.md +++ b/docs/helpers/Puppeteer.md @@ -27,8 +27,6 @@ Using `puppeteer-core` package, will prevent the download of browser binaries an > Experimental Firefox support [can be activated][2]. - - ## Configuration This helper should be configured in codecept.conf.js @@ -37,28 +35,28 @@ Type: [object][4] ### Properties -* `url` **[string][6]** base url of website to be tested -* `basicAuth` **[object][4]?** (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'} -* `show` **[boolean][23]?** show Google Chrome window for debug. -* `restart` **[boolean][23]?** restart browser between tests. -* `disableScreenshots` **[boolean][23]?** don't save screenshot on failure. -* `fullPageScreenshots` **[boolean][23]?** make full page screenshots on failure. -* `uniqueScreenshotNames` **[boolean][23]?** option to prevent screenshot override if you have scenarios with the same name in different suites. -* `trace` **[boolean][23]?** record [tracing information][27] with screenshots. -* `keepTraceForPassedTests` **[boolean][23]?** save trace for passed tests. -* `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. -* `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]. -* `highlightElement` **[boolean][23]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose). +- `url` **[string][6]** base url of website to be tested +- `basicAuth` **[object][4]?** (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'} +- `show` **[boolean][23]?** show Google Chrome window for debug. +- `restart` **[boolean][23]?** restart browser between tests. +- `disableScreenshots` **[boolean][23]?** don't save screenshot on failure. +- `fullPageScreenshots` **[boolean][23]?** make full page screenshots on failure. +- `uniqueScreenshotNames` **[boolean][23]?** option to prevent screenshot override if you have scenarios with the same name in different suites. +- `trace` **[boolean][23]?** record [tracing information][27] with screenshots. +- `keepTraceForPassedTests` **[boolean][23]?** save trace for passed tests. +- `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] | [Array][16]<[string][6]>)?** when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API][26]. 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]. +- `highlightElement` **[boolean][23]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose). ## findElement @@ -67,8 +65,8 @@ Note: Puppeteer Locator API doesn't have .first() method like Playwright ### Parameters -* `matcher` **[Object][4]** Puppeteer context to search within -* `locator` **([Object][4] | [string][6])** Locator specification +- `matcher` **[Object][4]** Puppeteer context to search within +- `locator` **([Object][4] | [string][6])** Locator specification Returns **[Promise][14]<[Object][4]>** Single ElementHandle object @@ -79,20 +77,18 @@ Note: Unlike Playwright, Puppeteer's Locator API doesn't have .all() method for ### Parameters -* `matcher` **[Object][4]** Puppeteer context to search within -* `locator` **([Object][4] | [string][6])** Locator specification +- `matcher` **[Object][4]** Puppeteer context to search within +- `locator` **([Object][4] | [string][6])** Locator specification Returns **[Promise][14]<[Array][16]>** Array of ElementHandle objects - - #### 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 +- `trace`: enables trace recording for failed tests; trace are saved into `output/trace` folder +- `keepTraceForPassedTests`: - save trace for passed tests #### Example #1: Wait for 0 network connections. @@ -170,7 +166,7 @@ Traces will be saved to `output/trace` #### Troubleshooting -Error Message: `No usable sandbox!` +Error Message: `No usable sandbox!` When running Puppeteer on CI try to disable sandbox if you see that message @@ -189,51 +185,47 @@ When running Puppeteer on CI try to disable sandbox if you see that message Receive Puppeteer client from a custom helper by accessing `browser` for the Browser object or `page` for the current Page object: ```js -const { browser } = this.helpers.Puppeteer; -await browser.pages(); // List of pages in the browser +const { browser } = this.helpers.Puppeteer +await browser.pages() // List of pages in the browser -const { page } = this.helpers.Puppeteer; -await page.url(); // Get the url of the current page +const { page } = this.helpers.Puppeteer +await page.url() // Get the url of the current page ``` ## Methods ### Parameters -* `config` +- `config` -### _addPopupListener +### \_addPopupListener Add the 'dialog' event listener to a page #### Parameters -* `page` +- `page` -### _getPageUrl +### \_getPageUrl Gets page URL including hash. -### _locate +### \_locate Get elements by different locator types, including strict locator Should be used in custom helpers: ```js -const elements = await this.helpers['Puppeteer']._locate({name: 'password'}); +const elements = await this.helpers['Puppeteer']._locate({ name: 'password' }) ``` - - - This action supports [React locators](https://codecept.io/react#locators) - #### Parameters -* `locator` +- `locator` -### _locateCheckable +### \_locateCheckable Find a checkbox by providing human-readable text: NOTE: Assumes the checkable element exists @@ -244,10 +236,10 @@ this.helpers['Puppeteer']._locateCheckable('I agree with terms and conditions'). #### Parameters -* `locator` -* `providedContext` +- `locator` +- `providedContext` -### _locateClickable +### \_locateClickable Find a clickable element by providing human-readable text: @@ -257,28 +249,24 @@ this.helpers['Puppeteer']._locateClickable('Next page').then // ... #### Parameters -* `locator` +- `locator` -### _locateElement +### \_locateElement Get single element by different locator types, including strict locator Should be used in custom helpers: ```js -const element = await this.helpers['Puppeteer']._locateElement({name: 'password'}); +const element = await this.helpers['Puppeteer']._locateElement({ name: 'password' }) ``` - - - This action supports [React locators](https://codecept.io/react#locators) - #### Parameters -* `locator` +- `locator` -### _locateFields +### \_locateFields Find field elements by providing human-readable text: @@ -288,15 +276,15 @@ this.helpers['Puppeteer']._locateFields('Your email').then // ... #### Parameters -* `locator` +- `locator` -### _setPage +### \_setPage Set current page #### Parameters -* `page` **[object][4]** page to set +- `page` **[object][4]** page to set ### acceptPopup @@ -310,9 +298,9 @@ Set the automatic popup response to Accept. This must be set before a popup is triggered. ```js -I.amAcceptingPopups(); -I.click('#triggerPopup'); -I.acceptPopup(); +I.amAcceptingPopups() +I.click('#triggerPopup') +I.acceptPopup() ``` ### amCancellingPopups @@ -321,9 +309,9 @@ Set the automatic popup response to Cancel/Dismiss. This must be set before a popup is triggered. ```js -I.amCancellingPopups(); -I.click('#triggerPopup'); -I.cancelPopup(); +I.amCancellingPopups() +I.click('#triggerPopup') +I.cancelPopup() ``` ### amOnPage @@ -332,14 +320,14 @@ Opens a web page in a browser. Requires relative or absolute url. If url starts with `/`, opens a web page of a site defined in `url` config parameter. ```js -I.amOnPage('/'); // opens main page of website -I.amOnPage('https://github.com'); // opens github -I.amOnPage('/login'); // opens a login page +I.amOnPage('/') // opens main page of website +I.amOnPage('https://github.com') // opens github +I.amOnPage('/login') // opens a login page ``` #### Parameters -* `url` **[string][6]** url path or global url. +- `url` **[string][6]** url path or global url. Returns **void** automatically synchronized promise through #recorder @@ -349,22 +337,20 @@ Appends text to a input field or textarea. Field is located by name, label, CSS or XPath ```js -I.appendField('#myTextField', 'appended'); +I.appendField('#myTextField', 'appended') // typing secret -I.appendField('password', secret('123456')); +I.appendField('password', secret('123456')) ``` #### Parameters -* `field` **([string][6] | [object][4])** located by label|name|CSS|XPath|strict locator -* `value` **[string][6]** text value to append. +- `field` **([string][6] | [object][4])** located by label|name|CSS|XPath|strict locator +- `value` **[string][6]** text value to append. Returns **void** automatically synchronized promise through #recorder - This action supports [React locators](https://codecept.io/react#locators) - ### attachFile > ⚠ There is an [issue with file upload in Puppeteer 2.1.0 & 2.1.1][7], downgrade to 2.0.0 if you face it. @@ -374,14 +360,14 @@ Path to file is relative current codecept directory (where codecept.conf.ts or c File will be uploaded to remote system (if tests are running remotely). ```js -I.attachFile('Avatar', 'data/avatar.jpg'); -I.attachFile('form input[name=avatar]', 'data/avatar.jpg'); +I.attachFile('Avatar', 'data/avatar.jpg') +I.attachFile('form input[name=avatar]', 'data/avatar.jpg') ``` #### Parameters -* `locator` **([string][6] | [object][4])** field located by label|name|CSS|XPath|strict locator. -* `pathToFile` **[string][6]** local file path relative to codecept.conf.ts or codecept.conf.js config file. +- `locator` **([string][6] | [object][4])** field located by label|name|CSS|XPath|strict locator. +- `pathToFile` **[string][6]** local file path relative to codecept.conf.ts or codecept.conf.js config file. Returns **void** automatically synchronized promise through #recorder @@ -398,15 +384,15 @@ I.blur('.text-area') ```js //element `#product-tile` is focused -I.see('#add-to-cart-btn'); +I.see('#add-to-cart-btn') I.blur('#product-tile') -I.dontSee('#add-to-cart-btn'); +I.dontSee('#add-to-cart-btn') ``` #### Parameters -* `locator` **([string][6] | [object][4])** field located by label|name|CSS|XPath|strict locator. -* `options` **any?** Playwright only: [Additional options][9] for available options object as 2nd argument. +- `locator` **([string][6] | [object][4])** field located by label|name|CSS|XPath|strict locator. +- `options` **any?** Playwright only: [Additional options][9] for available options object as 2nd argument. Returns **void** automatically synchronized promise through #recorder @@ -422,15 +408,15 @@ Element is located by label or name or CSS or XPath. The second parameter is a context (CSS or XPath locator) to narrow the search. ```js -I.checkOption('#agree'); -I.checkOption('I Agree to Terms and Conditions'); -I.checkOption('agree', '//form'); +I.checkOption('#agree') +I.checkOption('I Agree to Terms and Conditions') +I.checkOption('agree', '//form') ``` #### Parameters -* `field` **([string][6] | [object][4])** checkbox located by label | name | CSS | XPath | strict locator. -* `context` **([string][6]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. +- `field` **([string][6] | [object][4])** checkbox located by label | name | CSS | XPath | strict locator. +- `context` **([string][6]? | [object][4])** (optional, `null` by default) element located by CSS | XPath | strict locator. Returns **void** automatically synchronized promise through #recorder @@ -440,29 +426,29 @@ Clears a cookie by name, if none provided clears all cookies. ```js -I.clearCookie(); -I.clearCookie('test'); +I.clearCookie() +I.clearCookie('test') ``` #### Parameters -* `name` -* `cookie` **[string][6]?** (optional, `null` by default) cookie name +- `name` +- `cookie` **[string][6]?** (optional, `null` by default) cookie name ### clearField Clears a `