{"id":15062216,"url":"https://github.com/hdorgeval/puppeteer-core-controller","last_synced_at":"2025-04-10T10:04:17.327Z","repository":{"id":35027015,"uuid":"196851495","full_name":"hdorgeval/puppeteer-core-controller","owner":"hdorgeval","description":"Fluent API around puppeteer-core","archived":false,"fork":false,"pushed_at":"2024-02-21T13:31:38.000Z","size":1241,"stargazers_count":12,"open_issues_count":16,"forks_count":4,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-18T12:34:14.698Z","etag":null,"topics":["e2e","fluent-api","puppeteer","puppeteer-core","test-automation","test-runner"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/hdorgeval.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2019-07-14T15:15:36.000Z","updated_at":"2024-04-08T19:53:49.000Z","dependencies_parsed_at":"2025-02-16T23:32:36.694Z","dependency_job_id":"d2415113-1e6a-4bcd-a08a-6c8b7cf16df3","html_url":"https://github.com/hdorgeval/puppeteer-core-controller","commit_stats":null,"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdorgeval%2Fpuppeteer-core-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdorgeval%2Fpuppeteer-core-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdorgeval%2Fpuppeteer-core-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hdorgeval%2Fpuppeteer-core-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hdorgeval","download_url":"https://codeload.github.com/hdorgeval/puppeteer-core-controller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248198878,"owners_count":21063627,"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":["e2e","fluent-api","puppeteer","puppeteer-core","test-automation","test-runner"],"created_at":"2024-09-24T23:32:17.808Z","updated_at":"2025-04-10T10:04:17.294Z","avatar_url":"https://github.com/hdorgeval.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# puppeteer-core-controller\n\nFluent API around puppeteer-core\n\n[![Build Status](https://travis-ci.org/hdorgeval/puppeteer-core-controller.svg?branch=master)](https://travis-ci.org/hdorgeval/puppeteer-core-controller)\n[![Build status](https://ci.appveyor.com/api/projects/status/5q3m4m4s62knhb72?svg=true)](https://ci.appveyor.com/project/hdorgeval/puppeteer-core-controller)\n[![npm version](https://img.shields.io/npm/v/puppeteer-core-controller.svg)](https://www.npmjs.com/package/puppeteer-core-controller)\n\n- [Usage](#usage)\n- [Usage in an existing code base](#Usage-in-an-existing-code-base)\n- [Usage with Stories](#Usage-with-Stories)\n- [API Documentation](#API-Documentation)\n- [Selector API Documentation](#Selector-API-Documentation)\n\n# Usage\n\n```js\nimport { PuppeteerController } from 'puppeteer-core-controller';\n\nconst pptc = new PuppeteerController();\nconst emailInputSelector = 'input#exampleEmail';\nconst passwordInputSelector = 'input#examplePassword';\nconst checkMeOutSelector = 'input[type=\"checkbox\"].form-check-input';\nconst customSelect = 'select#exampleCustomSelect';\nconst option = 'Value 3';\n\nawait pptc\n  .initWith({\n    headless: false,\n  })\n  .withMaxSizeWindow()\n  .withCursor()\n  .navigateTo('https://reactstrap.github.io/components/form/')\n  .hover(emailInputSelector)\n  .click(emailInputSelector)\n  .typeText('foo.bar@baz.com')\n  .pressKey('Tab');\n  .expectThat(passwordInputSelector).hasFocus()\n  .typeText(\"don't tell!\")\n  .pressKey('Tab');\n  .expectThat(passwordInputSelector).hasClass('is-valid')\n  .hover(checkMeOutSelector)\n  .click(checkMeOutSelector)\n  .select(option).in(customSelect)\n  .close();\n```\n\n# Usage in an existing code base\n\n```js\nimport { PuppeteerController } from 'puppeteer-core-controller';\n\n// existing code that has a browser and page instance\n// ...\n\nconst pptc = new PuppeteerController(browser, page);\nconst emailInputSelector = 'input#exampleEmail';\nconst passwordInputSelector = 'input#examplePassword';\nconst checkMeOutSelector = 'input[type=\"checkbox\"].form-check-input';\nconst customSelect = 'select#exampleCustomSelect';\nconst option = 'Value 3';\n\nawait pptc\n  .navigateTo('https://reactstrap.github.io/components/form/')\n  .click(emailInputSelector)\n  .typeText('foo.bar@baz.com')\n  .pressKey('Tab');\n  .expectThat(passwordInputSelector).hasFocus()\n  .typeText(\"don't tell!\")\n  .pressKey('Tab');\n  .expectThat(passwordInputSelector).hasClass('is-valid')\n  .click(checkMeOutSelector)\n  .select(option).in(customSelect)\n  .close();\n```\n\n# Usage with Stories\n\n```js\nimport { PuppeteerController, Story, StoryWithProps } from 'puppeteer-core-controller';\n\nconst pptc = new PuppeteerController();\nconst launchOptions: LaunchOptions = {\n  headless: true,\n};\nconst url = 'https://reactstrap.github.io/components/form';\nconst customSelect = 'select#exampleCustomSelect';\nconst option = 'Value 3';\n\ninterface StartOptions {\n  launchOptions: LaunchOptions;\n  url: string;\n}\n\nconst openApplication: StoryWithProps\u003cStartOptions\u003e = async (pptc, props) =\u003e {\n  await pptc\n    .initWith(props.launchOptions)\n    .withMaxSizeWindow()\n    .withCursor()\n    .navigateTo(props.url);\n};\n\nconst fillForm: Story = async (pptc) =\u003e {\n  await pptc\n    .click(customSelect)\n    .select(option)\n    .in(customSelect);\n};\n\nconst params: StartOptions = { launchOptions, url };\nawait pptc\n  .runStory(openApplication, params)\n  .runStory(fillForm)\n  .close();\n```\n\n# API Documentation\n\n- Chainable Methods\n\n  - [initWith([options])](#initWithoptions)\n  - [recordFailedRequests([options])](#recordFailedRequestsoptions)\n  - [recordPageErrors()](#recordPageErrors)\n  - [recordRequestsTo(url)](#recordRequestsTourl)\n  - [withMaxSizeWindow([minViewPort])](#withMaxSizeWindowminViewPort)\n  - [withCursor()](#withCursor)\n  - [emulateDevice(deviceName)](#emulateDevicedeviceName)\n  - [navigateTo(url[, options])](#navigateTourl-options)\n  - [hover(selector[, options])](#hoverselector-options)\n  - [clear(selector[, options])](#clearselector-options)\n  - [click(selector[, options])](#clickselector-options)\n  - [pasteText(text[, options])](#pasteTexttext-options)\n  - [typeText(text[, options])](#typeTexttext-options)\n  - [pressKey(key[, options])](#pressKeykey-options)\n  - [select(values).in(selector[, options])](#selectvaluesinselector-options)\n  - [find(selector[, waitOptions]).withText(text).click([clickOptions])](#findselector-waitOptionswithTexttextclickclickOptions)\n  - [find(selector[, waitOptions]).withExactText(text).click([clickOptions])](#findselector-waitOptionswithExactTexttextclickclickOptions)\n  - [runStory(story)](#runStorystory)\n  - [wait(duration)](#waitduration)\n  - [waitForStabilityOf(func[, waitOptions[, errorMessage]])](#waitForStabilityOffunc-waitOptions-errorMessage)\n  - [waitUntil(predicate[, waitOptions[, errorMessage]])](#waitUntilpredicate-waitOptions-errorMessage)\n\n- Chainable Assertions\n\n  - [expectThat(selector).hasAttribute(attributeName).withValue(attributeValue,[options])](#expectThatselectorhasAttributeattributeNamewithValueattributeValueoptions)\n  - [expectThat(selector).hasClass(className,[options])](#expectThatSelectorhasClassclassNameoptions)\n  - [expectThat(selector).hasExactValue(value,[options])](#expectThatselectorhasexactvaluevalueoptions)\n  - [expectThat(selector).hasFocus([options])](#expectThatselectorhasFocusoptions)\n  - [expectThat(selector).hasText(text,[options])](#expectThatselectorhastexttextoptions)\n  - [expectThat(selector).isDisabled([options])](#expectThatselectorisDisabledoptions)\n  - [expectThat(selector).isEnabled([options])](#expectThatselectorisEnabledoptions)\n  - [expectThat(selector).isVisible([options])](#expectThatselectorisVisibleoptions)\n  - [expectThat(selector).isNotVisible([options])](#expectThatselectorisNotVisibleoptions)\n\n- Helper Methods and Properties\n\n  - [cast(any)](#castany)\n  - [clearFailedRequests()](#clearFailedRequests)\n  - [clearRequestsTo(url)](#clearRequestsTourl)\n  - [clearPageErrors()](#clearPageErrors)\n  - [currentPage](#currentPage)\n  - [getClientRectangleOf(selector)](#getClientRectangleOfselector)\n  - [getComputedStyleOf(selector)](#getComputedStyleOfselector)\n  - [getCurrentUrl()](#getCurrentUrl)\n  - [getFailedRequests()](#getFailedRequests)\n  - [getInnerTextOf(selector)](#getInnerTextOfselector)\n  - [getInstances()](#getInstances)\n  - [getPageErrors()](#getPageErrors)\n  - [getSelectedOptionOf(selector)](#getSelectedOptionOfselector)\n  - [getAllOptionsOf(selector)](#getAllOptionsOfselector)\n  - [getLastRequestTo(url)](#getLastRequestTourl)\n  - [getRequestsTo(url)](#getRequestsTourl)\n  - [getValueOf(selector)](#getValueOfselector)\n  - [isChecked(selector)](#isCheckedselector)\n  - [isDisabled(selector)](#isDisabledselector)\n  - [isVisible(selector)](#isVisibleselector)\n  - [isNotVisible(selector)](#isNotVisibleselector)\n  - [stringifyRequest(request)](#stringifyRequestrequest)\n  - [takeFullPageScreenshotAsBase64([options])](#takeFullPageScreenshotAsBase64options)\n\n## Chainable Methods\n\n### initWith([options])\n\n- options: same object as [puppeteer.launch([options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#puppeteerlaunchoptions)\n\n---\n\n### withMaxSizeWindow([minViewPort])\n\n- maximize the window size. Should be called after `initWith` and before all other actions.\n\n- minViewPort: {minWidth: number, minHeight: number }\n  This method might not work on CI environment. In this case setup the minViewPort parameter to ensure the page has a minimum width and height.\n\n---\n\n### withCursor()\n\n- show a cursor that is bound to the current mouse position. This method should be called before navigateTo(url).\n\n![demo withCursor](demos/withCursor.gif)\n\n---\n\n### emulateDevice(deviceName)\n\nEmulates a mobile device.\n\n- deviceName: `DeviceName`. See the [list of all known devices](lib/actions/page-actions/emulate-device/device-names.ts).\n\n---\n\n### recordPageErrors()\n\n- track and record page errors. Should be called after `initWith`.\n- use `getPageErrors()` helper method on the controller to access errors that have occurred.\n- use `clearPageErrors()` helper method on the controller to clear all past errors.\n\n---\n\n### recordFailedRequests([options])\n\n- track and record failed requests. Should be called after `initWith`. All requests with the following HTTP response status will be recorded as failed requests: `500, 503, 400, 401, 403, 404, 307`.\n\n- use `getFailedRequests()` helper method on the controller to access errors that have occurred.\n- use `clearFailedRequests()` helper method on the controller to clear all past errors.\n\n- options: `...number[]`\n  - add any HTTP status that should be processed as failed request.\n\n---\n\n### recordRequestsTo(url)\n\n- url: `string`\n\n- track and record requests whose url contains the input url. Should be called after `initWith`.\n\n- use `getRequestsTo(url)` helper method on the controller to access all requests that have occurred with this `url`.\n\n- use `getLastRequestTo(url)` helper method on the controller to access the last request that has occurred with this `url`.\n\n- use `clearRequestsTo(url)` helper method on the controller to clear all past requests with this `url`.\n\n---\n\n### navigateTo(url[, options])\n\nNavigate to the specified url\n\n- url: `string`\n- options: same object as [page.goto(url[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pagegotourl-options)\n\n---\n\n### click(selector[, options])\n\n- selector: `string`\n- options: same object as [page.click(selector[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pageclickselector-options)\n\n  with an additional property: `timeoutInMilliseconds`. This option enables the click method to wait for the selector to appear in the DOM before attempting to click on it. Defaults to 30000 (30 seconds). Pass 0 to disable this timeout.\n\n---\n\n### hover(selector[, options])\n\n- selector: `string`\n- options: {steps: number, timeoutInMilliseconds: number }\n\n  `timeoutInMilliseconds` option enables the hover method to wait for the selector to appear in the DOM before attempting to move the mouse on it. Defaults to 30000 (30 seconds). Pass 0 to disable this timeout.\n\n---\n\n### pasteText(text[, options])\n\n- text: `string`\n- options: `PasteOptions`\n\nPaste text in the element that is currently active (that has the focus) on the page.\nIf the element does not handle the 'paste' event through an explicit event handler, then you must set the option {handlePasteEvent: true}.\nWhen you set this option to true, the controller will automatically attach a basic 'paste' event handler.\n\n```js\ninterface PasteOptions {\n  handlePasteEvent: boolean;\n}\n```\n\n```js\nawait pptc\n  .initWith(launchOptions)\n  .navigateTo(url)\n  .click(selector)\n  .clear(selector)\n  .pasteText('foo bar');\n```\n\n---\n\n### typeText(text[, options])\n\n- text: `string`\n- options: same object as [keyboard.type(text[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#keyboardtypetext-options)\n\n  except that `delay` defaults to 50 milliseconds. Set the `delay` value to `0` to disable the delay.\n\n---\n\n### clear(selector[, options])\n\nClear text in an input box.\n\n- selector: `string`\n- options: same object as [page.click(selector[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pageclickselector-options)\n\nThis method does not wait for the selector to be in the DOM.\nIn some cases you might have to wait that the input field is visible before clearing it's value:\n\n```js\nconst value = await pptc\n  .expectThat(selector)\n  .isVisible()\n  .hover(selector)\n  .clear(selector);\n```\n\n---\n\n### pressKey(key[, options])\n\n- key: 'Tab' | 'Backspace' | 'Enter'\n- options: same object as [keyboard.press(key[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#keyboardpresskey-options)\n\n  except that `delay` defaults to 50 milliseconds. Set the `delay` value to `0` to disable the delay.\n\n---\n\n### select(values).in(selector[, options])\n\n- values : `string[]`\n\n  There is a major difference between the `select` method of the Puppeteer API and this `select` method: You should pass the labels of the select DOM element (ie: what you see on the screen) instead of the value of the `value` attribute found on the `option` element.\n\n- selector: same as [page.select(selector, ...values)](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pageselectselector-values)\n\n- options: {timeoutInMilliseconds}. This option enables the select method to wait for the selector to appear in the DOM before attempting to select the option(s). Defaults to 30000 (30 seconds). Pass 0 to disable this timeout.\n\n```html\n\u003cselect id=\"select\"\u003e\n  \u003coption value=\"value1\" selected\u003evalue 1\u003c/option\u003e\n  \u003coption value=\"value2\"\u003evalue 2\u003c/option\u003e\n  \u003coption value=\"value3\"\u003evalue 3\u003c/option\u003e\n\u003c/select\u003e\n```\n\n```js\nawait pptc.select('value 2').in(selector);\n```\n\n---\n\n### find(selector[, waitOptions]).withText(text).click([clickOptions])\n\nfind a selector whose innerText property contains `text`, then click on it.\n\n```js\nawait pptc\n  .initWith({ headless: true })\n  .withCursor()\n  .navigateTo('https://reactstrap.github.io')\n  .find('a.btn')\n  .withText('Components')\n  .click();\n```\n\n- selector: `string`\n- waitOptions: {timeoutInMilliseconds: number}.\n  The find method will wait for the selector to to be visible until `timeoutInMilliseconds` expires. Defaults to 30000 (30 seconds).\n- withText(text)\n- clickOptions: same object as [page.click(selector[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pageclickselector-options)\n\n---\n\n### find(selector[, waitOptions]).withExactText(text).click([clickOptions])\n\nfind a selector whose innerText property is exactly equal to `text`, then click on it.\n\n```js\nawait pptc\n  .initWith({ headless: true })\n  .withCursor()\n  .navigateTo('https://reactstrap.github.io')\n  .find('a.btn')\n  .withExactText('Components')\n  .click();\n```\n\n- selector: `string`\n- waitOptions: {timeoutInMilliseconds: number}.\n  The find method will wait for the selector to to be visible until `timeoutInMilliseconds` expires. Defaults to 30000 (30 seconds).\n- withExactText(text)\n- clickOptions: same object as [page.click(selector[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pageclickselector-options)\n\n---\n\n### runStory(story)\n\n- story: `Story | StoryWithProps`\n\n---\n\n### wait(duration)\n\n- duration: `number`\n\n  time to wait in milliseconds.\n\n---\n\n### waitUntil(predicate[, waitOptions[, errorMessage]])\n\n- predicate: `() =\u003e Promise\u003cboolean\u003e`\n- waitOptions: `Partial\u003cWaitUntilOptions\u003e`\n- errorMessage: `string | (() =\u003e Promise\u003cstring\u003e`\n\nWait until predicate becomes true.\n\n```js\ninterface WaitUntilOptions {\n  /**\n   * Defaults to 30000 milliseconds.\n   *\n   * @type {number}\n   * @memberof WaitUntilOptions\n   */\n  timeoutInMilliseconds: number;\n\n  /**\n   * Time during which the callback must always return true.\n   * Defaults to 300 milliseconds.\n   * You must not setup a duration \u003c 100 milliseconds.\n   * @type {number}\n   * @memberof AssertOptions\n   */\n  stabilityInMilliseconds: number;\n\n  /**\n   * Throw a timeout exception when the callback still returns false.\n   * Defaults to false.\n   * @type {boolean}\n   * @memberof WaitUntilOptions\n   */\n  throwOnTimeout: boolean;\n\n  /**\n   * Output to the console all steps of the waiting mechanism.\n   * Defaults to false.\n   * Use this option when the waitUntil() method does not wait as expected.\n   *\n   * @type {boolean}\n   * @memberof WaitUntilOptions\n   */\n  verbose: boolean;\n}\n```\n\nUsage example:\n\n```js\nconst selector = pptc\n  .selector('[role=\"row\"]')\n  .find('td')\n  .withText('hidden, then visible')\n  .find('p');\n\nawait pptc\n  .initWith(launchOptions)\n  .navigateTo(url)\n  .waitUntil(() =\u003e selector.isVisible());\n```\n\n---\n\n### waitForStabilityOf(func[, waitOptions[, errorMessage]])\n\n- func: `() =\u003e Promise\u003cstring | number\u003e`\n- waitOptions: `Partial\u003cWaitUntilOptions\u003e`\n- errorMessage: `string | (() =\u003e Promise\u003cstring\u003e`\n\nWaits until the function `func()` returns the same result during a specified period of time.\n\n```js\ninterface WaitUntilOptions {\n  /**\n   * Defaults to 30000 milliseconds.\n   *\n   * @type {number}\n   * @memberof WaitUntilOptions\n   */\n  timeoutInMilliseconds: number;\n\n  /**\n   * Time during which the callback must always return true.\n   * Defaults to 300 milliseconds.\n   * You must not setup a duration \u003c 100 milliseconds.\n   * @type {number}\n   * @memberof AssertOptions\n   */\n  stabilityInMilliseconds: number;\n\n  /**\n   * Throw a timeout exception when the callback still returns false.\n   * Defaults to false.\n   * @type {boolean}\n   * @memberof WaitUntilOptions\n   */\n  throwOnTimeout: boolean;\n\n  /**\n   * Output to the console all steps of the waiting mechanism.\n   * Defaults to false.\n   * Use this option when the waitUntil() method does not wait as expected.\n   *\n   * @type {boolean}\n   * @memberof WaitUntilOptions\n   */\n  verbose: boolean;\n}\n```\n\nUsage example:\n\n```js\nconst selector = pptc.selector('[role=\"row\"]'); // will select all rows in a grid\n\nawait pptc\n  .initWith(launchOptions)\n  .navigateTo(url)\n  .waitForStabilityOf(() =\u003e selector.count()); // waits until the number of rows is stable\n```\n\n---\n\n## Assertion API\n\n### Assert Options\n\nEvery method in the Assertion API may use `options` to customize the behavior of the internal waiting mechanism:\n\n```ts\ninterface AssertOptions {\n  /**\n   * Defaults to 30000 milliseconds.\n   *\n   * @type {number}\n   * @memberof AssertOptions\n   */\n  timeoutInMilliseconds: number;\n  /**\n   * time during which the Assert must give back the same result.\n   * Defaults to 300 milliseconds.\n   * You must not setup a duration \u003c 100 milliseconds.\n   * @type {number}\n   * @memberof AssertOptions\n   */\n  stabilityInMilliseconds: number;\n}\n```\n\n### expectThat(selector).hasAttribute(attributeName).withValue(attributeValue,[options])\n\n- selector: `string`\n- attributeName: `string`\n- attributeValue: `string`\n- options: `Partial\u003cAssertOptions\u003e`\n\n  {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to have the specified value. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n```js\nawait pptc\n  .expectThat(selector)\n  .hasAttribute('foo')\n  .withValue('bar');\n```\n\n---\n\n### expectThat(selector).hasFocus([options])\n\n- selector: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to have the focus. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n---\n\n### expectThat(selector).hasClass(className,[options])\n\n- selector: `string`\n- className: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to have the specified class. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n---\n\n### expectThat(selector).hasExactValue(value,[options])\n\n- selector: `string`\n- value: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to have the specified value. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n```js\nawait pptc\n  .click(emailInputSelector)\n  .typeText('foo.bar@baz.com')\n  .expectThat(emailInputSelector)\n  .hasExactValue('foo.bar@baz.com');\n```\n\n---\n\n### expectThat(selector).hasText(text,[options])\n\n- selector: `string`\n- text: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to have the specified value. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n```js\nawait pptc\n  .expectThat(selector)\n  .isVisible()\n  .expectThat(selector)\n  .hasText(text);\n```\n\n---\n\n### expectThat(selector).isDisabled([options])\n\n- selector: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to be disabled. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n---\n\n### expectThat(selector).isEnabled([options])\n\n- selector: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to be enabled. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n---\n\n### expectThat(selector).isVisible([options])\n\n- selector: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to be visible. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n---\n\n### expectThat(selector).isNotVisible([options])\n\n- selector: `string`\n- options: {timeoutInMilliseconds}. This option enables the assertion mechanism to wait for the selector to be hidden or to disappear from the DOM. Defaults to 30000 (30 seconds).\n  See [Assert Options](#Assert-Options).\n\n---\n\n## Helper Methods and Properties\n\n### getComputedStyleOf(selector)\n\n- selector: `string`\n- returns: `Promise\u003cCSSStyleDeclaration\u003e`\n\n  ```js\n  const validInput = 'input[type=\"text\"].is-valid.form-control';\n  const computedStyles = await pptc.getComputedStyleOf(validInput);\n  expect(computedStyles.borderColor).toBe('rgb(40, 167, 69)');\n  ```\n\n---\n\n### getClientRectangleOf(selector)\n\n- selector: `string`\n\n  ```js\n  const selector = 'input[type=\"text\"].is-valid.form-control';\n  const selectorClientRectangle = await pptc.getClientRectangleOf(selector);\n\n  const middleX = selectorClientRectangle.left + selectorClientRectangle.width / 2;\n  const middleY = selectorClientRectangle.top + selectorClientRectangle.height / 2;\n\n  const expectedMiddleX = 100;\n  const expectedMiddleY = 100;\n\n  expect(Math.abs(middleX - expectedMiddleX)).toBeLessThanOrEqual(1);\n  expect(Math.abs(middleY - expectedMiddleY)).toBeLessThanOrEqual(1);\n  ```\n\n---\n\n### getCurrentUrl()\n\n- returns: `Promise\u003cstring\u003e`\n\n---\n\n### isChecked(selector)\n\n- selector: `string`\n- returns: `Promise\u003cboolean\u003e`\n\n---\n\n### isDisabled(selector)\n\n- selector: `string`\n- returns: `Promise\u003cboolean\u003e`\n\n---\n\n### isVisible(selector)\n\n- selector: `string`\n- returns: `Promise\u003cboolean\u003e`\n\n---\n\n### isNotVisible(selector)\n\n- selector: `string`\n- returns: `Promise\u003cboolean\u003e`\n\n---\n\n### getAllOptionsOf(selector)\n\n- selector: `string`\n- returns: `Promise\u003cSelectOptionInfo[]\u003e`\n\n```ts\nSelectOptionInfo {\n  value: string;\n  label: string;\n  selected: boolean;\n}\n```\n\n---\n\n### getSelectedOptionOf(selector)\n\n- selector: `string`\n- returns: `Promise\u003cSelectOptionInfo | null\u003e`\n\n---\n\n### getValueOf(selector)\n\n- selector: `string`\n- returns: `Promise\u003cstring\u003e`\n\nThis method does not wait for the selector to be in the DOM.\nIn some cases you might have to wait that the input field is visible before getting it's value:\n\n```js\nconst value = await pptc\n  .expectThat(selector)\n  .isVisible()\n  .getValueOf(selector);\n```\n\n---\n\n### getInnerTextOf(selector)\n\n- selector: `string`\n- returns: `Promise\u003cstring\u003e`\n\nThis method does not wait for the selector to be in the DOM.\nIn some cases you might have to wait that the input field is visible before getting it's value:\n\n```js\nconst text = await pptc\n  .expectThat(selector)\n  .isVisible()\n  .getInnerTextOf(selector);\n```\n\n---\n\n### takeFullPageScreenshotAsBase64([options])\n\n- options: same object as [page.screenshot([options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pagescreenshotoptions)\n\n  ```js\n  const screenshot = await pptc.takeFullPageScreenshotAsBase64();\n  ```\n\n---\n\n### currentPage\n\n- get page instance of the controller in order to do stuff not covered by this API.\n\n  ```js\n  const pptc = new PuppeteerController();\n\n  // use the pptc controller API\n  // ...\n\n  const page = pptc.currentPage; // this is a property\n  // now use this page instance through the puppeteer API\n  ```\n\n---\n\n### getInstances()\n\n- get browser and page instances of the controller in order to do stuff not covered by this API.\n\n  ```js\n  const pptc = new PuppeteerController();\n\n  // use the pptc controller API\n  // ...\n\n  const [browser, page] = pptc.getIntances();\n  // now use the browser and page instances through the puppeteer API\n  ```\n\n---\n\n### getPageErrors()\n\n- get page errors that occurred while executing the test.\n\n  ```js\n  await pptc\n      .initWith(launchOptions)\n      .recordPageErrors()\n      .navigateTo(url)\n      ...\n      .close();\n\n  const errors: Error[] = pptc.getPageErrors();\n  // analyse errors by iterating on the returned array\n  // an empty array means that no error has occurred or that you forgot to call the recordPageErrors() method\n  ```\n\n---\n\n### clearPageErrors()\n\n- clear page errors that occurred. Usefull if you want to track page errors only after a specific context has been setup on the page.\n\n---\n\n### getFailedRequests()\n\n- get failed requests that occurred while executing the test.\n- returns: `Request[]`.\n\n  See [Request](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-request)\n\n  ```js\n  await pptc\n      .initWith(launchOptions)\n      .recordFailedRequests()\n      .navigateTo(url)\n      ...\n      .close();\n\n  const errors: puppeteer.Request[] = pptc.getFailedRequests();\n  // analyse errors by iterating on the returned array\n  // an empty array means that no error has occurred or that you forgot to call the recordFailedRequests() method\n  ```\n\n---\n\n### clearFailedRequests()\n\n- clear failed requests that occurred. Usefull if you want to track failed requests only after a specific context has been setup on the page.\n\n---\n\n### getRequestsTo(url)\n\n- get requests to specific `url` that occurred while executing the test.\n- url : `string`\n- returns: `Request[]`.\n\n  See [Request](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-request)\n\n  ```js\n  await pptc\n      .initWith(launchOptions)\n      .recordRequestsTo('/foobar')\n      .navigateTo(url)\n      ...\n      .close();\n\n  const requests: puppeteer.Request[] = pptc.getRequestsTo('/foobar');\n  // analyse requests by iterating on the returned array\n  // an empty array means that no request has occurred\n  // or that you forgot to call the recordRequestsTo(url) method,\n  // or you have called this method too early.\n  ```\n\n---\n\n### getLastRequestTo(url)\n\n- get last request to specific `url` that occurred while executing the test.\n- url : `string`\n- returns: `Request`.\n\n  See [Request](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-request)\n\n  ```js\n  await pptc\n      .initWith(launchOptions)\n      .recordRequestsTo('/foobar')\n      .navigateTo(url)\n      ...\n      .close();\n\n  const request: puppeteer.Request = pptc.getLastRequestTo('/foobar');\n  // an undefined result means that no request has occurred\n  // or that you forgot to call the recordRequestsTo(url) method,\n  // or you have called this method too early.\n  ```\n\n---\n\n### clearRequestsTo(url)\n\n- url : `string`\n\n- clear requests that occurred to the `url`. Usefull if you want to track requests only after a specific context has been setup on the page.\n\n---\n\n### stringifyRequest(request)\n\nTransforms the Puppeteer request object into a stringified JSON object.\n\n- request : `Request` (See [Request](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-request))\n- returns: `string`\n\nThe stringified result can be converted back to a JSON of type `RequestInfo`\n\n```js\ninterface RequestInfo {\n  url: string;\n  method: string;\n  error: {\n    errorText: string,\n  } | null;\n  headers: { [key: string]: string };\n  postData: string | unknown | undefined;\n  response: ResponseInfo | null;\n}\n\ninterface ResponseInfo {\n  headers: { [key: string]: string };\n  status: number;\n  payload: string | unknown | undefined;\n}\n```\n\n```js\nimport {RequestInfo} from 'puppeteer-core-controller';\n\nawait pptc\n    .initWith(launchOptions)\n    .recordRequestsTo('/foobar')\n    .navigateTo(url)\n    ...\n\nconst request: puppeteer.Request = pptc.getLastRequestTo('/foobar');\n\nconst stringifiedRequest = await pptc.stringifyRequest(request);\nconsole.log(stringifiedRequest);\n\nconst requestInfo = JSON.parse(stringifiedRequest) as RequestInfo\n// now you can safely examine all parts of the request and the response\n```\n\n---\n\n### cast(any)\n\n- cast input object as a PuppeteerController instance; usefull when a PuppeteerController instance is stored in an untyped context like in cucumberJS.\n\n```js\nconst pptc = cast(this.context.pptc);\n// use the pptc controller API\n// ...\n```\n\n---\n\n# Selector API Documentation\n\n- Chainable Methods\n\n  - [find(selector)](#findselector)\n  - [nth(index)](#nthindex)\n  - [parent()](#parent)\n  - [withText(text)](#withTexttext)\n  - [withValue(text)](#withValuetext)\n\n- Helper Methods\n\n  - [click([options])](#clickoptions)\n  - [count()](#count)\n  - [doesNotExist()](#doesNotExist)\n  - [doubleClick([options])](#doubleClickoptions)\n  - [exists()](#exists)\n  - [getFirstHandleOrNull()](#getFirstHandleOrNull)\n  - [getHandles()](#getHandles)\n  - [hasClass(className)](#hasClassclassName)\n  - [hover([options])](#hoveroptions)\n  - [isDisabled()](#isDisabled)\n  - [isEnabled()](#isEnabled)\n  - [isVisible()](#isVisible)\n\n## Usage\n\nThe Selector API enables to find and target a DOM element or a collection of DOM elements that is embedded in complex DOM Hierarchy.\n\nTo use the Selector API, you must get a selector object from the controller:\n\n```ts\nimport { PuppeteerController } from 'puppeteer-core-controller';\n\nconst pptc = new PuppeteerController();\nconst selector = pptc\n  .selector('[role=\"row\"]') // will get all dom elements, within the current page, with the attribute role=\"row\"\n  .withText('foobar') // will filter only those that contains the text 'foobar'\n  .find('td') // from previous result(s), find all embedded \u003ctd\u003e elements\n  .nth(2); // take only the second cell\n```\n\nOnce you have build a selector object, you can 'execute' the search at any time and get the found elements:\n\n```js\nconst handles = await selector.getHandles();\n```\n\nIf the selector targets only one DOM element, you can 'execute' the search at any time and get the found element:\n\n```js\nconst handle = await selector.getFirstHandleOrNull();\n```\n\n## Chainable Methods\n\n### find(selector)\n\n- selector: `string`\n\nFinds all `selector` elements starting from previous found elements.\n\n---\n\n### withText(text)\n\n- text: `string`\n\nFinds, from previous search, all elements whose innerText contains the specified text.\n\n---\n\n### withValue(text)\n\n- text: `string`\n\nFinds, from previous search, all elements whose value contains the specified text.\n\n---\n\n### nth(index)\n\n- index: `number` (1-based index)\n\n---\n\n### parent()\n\n- index: `number` (1-based index)\n\nGet the parent of each elements found in the previous step.\n\n---\n\n## Helper Methods\n\n### getHandles()\n\n- returns: `Promise\u003cElementHandle\u003cElement\u003e[]\u003e`\n\n  see [class: ElementHandle](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-elementhandle)\n\n  Executes the search. Will return an empty array if no elements are found, will return all found elements otherwise.\n\n  The result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\n---\n\n### getFirstHandleOrNull()\n\n- returns: `Promise\u003cElementHandle\u003cElement\u003e | null\u003e`\n\n  see [class: ElementHandle](https://github.com/puppeteer/puppeteer/blob/master/docs/api.md#class-elementhandle)\n\n  Executes the search and returns the first found element. Will return null if no elements are found.\n\n  The result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\n---\n\n### exists()\n\n- returns: `Promise\u003cboolean\u003e`\n\nChecks if the selector exists.\n\nThe result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\nIn order to be able to call this method not too early, use the [waitUntil(predicate[, waitOptions[, errorMessage]])](#waitUntilpredicate-waitOptions-errorMessage) method:\n\n```js\nimport { PuppeteerController } from 'puppeteer-core-controller';\n\nconst pptc = new PuppeteerController();\nconst selector = pptc\n  .selector('[role=\"row\"]') // will get all dom elements, within the current page, with the attribute role=\"row\"\n  .withText('foobar') // will filter only those that contains the text 'foobar'\n  .find('td') // from previous result(s), find all embedded \u003ctd\u003e elements\n  .nth(2); // take only the second cell\n\nawait pptc.waitUntil(() =\u003e selector.exists());\nconst selectorExists = await selector.exists();\nif (selectorExists) {\n  // do something only when the selector exists in DOM\n}\n```\n\n---\n\n### doesNotExist()\n\n- returns: `Promise\u003cboolean\u003e`\n\nChecks if the selector does not exist.\n\nThe result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\nIn order to be able to call this method not too early, use the [waitUntil(predicate[, waitOptions[, errorMessage]])](#waitUntilpredicate-waitOptions-errorMessage) method:\n\n```js\nimport { PuppeteerController } from 'puppeteer-core-controller';\n\nconst pptc = new PuppeteerController();\nconst selector = pptc\n  .selector('[role=\"row\"]') // will get all dom elements, within the current page, with the attribute role=\"row\"\n  .withText('foobar') // will filter only those that contains the text 'foobar'\n  .find('td') // from previous result(s), find all embedded \u003ctd\u003e elements\n  .nth(2); // take only the second cell\n\nawait pptc.waitUntil(() =\u003e selector.doesNotExist());\nconst isRemoved = await selector.doesNotExist();\nif (isRemoved) {\n  // do something only when the selector is removed from DOM\n}\n```\n\n---\n\n### isVisible()\n\n- returns: `Promise\u003cboolean\u003e`\n\nChecks if the selector is visible.\n\nIf the selector targets multiple DOM elements, this check is done only on the first one found.\n\nThe result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\n---\n\n### isDisabled()\n\n- returns: `Promise\u003cboolean\u003e`\n\nChecks if the selector is disabled.\n\nIf the selector targets multiple DOM elements, this check is done only on the first one found.\n\nThe result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\n---\n\n### isEnabled()\n\n- returns: `Promise\u003cboolean\u003e`\n\nChecks if the selector is enabled.\n\nIf the selector targets multiple DOM elements, this check is done only on the first one found.\n\nThe result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\nIn order to be able to call this method not too early, use the [waitUntil(predicate[, waitOptions[, errorMessage]])](#waitUntilpredicate-waitOptions-errorMessage) method:\n\n```js\nimport { PuppeteerController } from 'puppeteer-core-controller';\n\nconst pptc = new PuppeteerController();\nconst selector = pptc\n  .selector('[role=\"row\"]') // will get all dom elements, within the current page, with the attribute role=\"row\"\n  .find('input') // from previous result(s), find all embedded \u003cinput\u003e elements\n  .nth(2); // take only the second input\n\nawait pptc.waitUntil(() =\u003e selector.isEnabled());\nconst isEnabled = await selector.isEnabled();\nif (isEnabled) {\n  // do something only when the selector is enabled\n}\n```\n\n---\n\n### count()\n\n- returns: `Promise\u003cnumber\u003e`\n\nGets the number of found elements.\n\nThe result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\n---\n\n### click([options])\n\n- options: same object as [page.click(selector[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pageclickselector-options)\n\n  with an additional property: `timeoutInMilliseconds`. This option enables the click method to wait for the selector to appear in the DOM before attempting to click on it. Defaults to 30000 (30 seconds).\n\n- This method automatically waits for the selector to appear in the DOM:\n  - then hover over the selector;\n  - then waits for the selector to be enabled (ie: no disabled attribute)\n  - then clicks on the selector.\n\n---\n\n### doubleClick([options])\n\n- options: same object as [page.click(selector[, options])](https://github.com/puppeteer/puppeteer/blob/v2.0.0/docs/api.md#pageclickselector-options)\n\n  with an additional property: `timeoutInMilliseconds`. This option enables the click method to wait for the selector to appear in the DOM before attempting to double-click on it. Defaults to 30000 (30 seconds).\n\n  the `delay` option enables to configure the delay between the two clicks, defaults to 100ms.\n\n- This method automatically waits for the selector to appear in the DOM:\n  - then hover over the selector;\n  - then waits for the selector to be enabled (ie: no disabled attribute)\n  - then double-clicks on the selector.\n\n---\n\n### hover([options])\n\n- options: {steps: number, timeoutInMilliseconds: number }\n\n  `timeoutInMilliseconds` option enables the hover method to wait for the selector to appear in the DOM before attempting to move the mouse on it. Defaults to 30000 (30 seconds). Pass 0 to disable this timeout.\n\n  with an additional property: `timeoutInMilliseconds`. This option enables the click method to wait for the selector to appear in the DOM before attempting to click on it. Defaults to 30000 (30 seconds).\n\n---\n\n### hasClass(className)\n\n- className : `string`\n- returns: `Promise\u003cboolean\u003e`\n\nChecks if selector has specified class.\nIf the selector targets multiple DOM elements, this check is done only on the first one found.\n\nThe result may differ from one execution to another especially if targeted element is rendered lately because its data is based on some backend response.\n\nIn order to be able to call this method not too early, use the [waitUntil(predicate[, waitOptions[, errorMessage]])](#waitUntilpredicate-waitOptions-errorMessage) method:\n\n```js\nimport { PuppeteerController } from 'puppeteer-core-controller';\n\nconst pptc = new PuppeteerController();\nconst selector = pptc.selector('p').withText('lorem ipsum ...');\n\nawait pptc.waitUntil(() =\u003e selector.hasClass('foobar'));\nconst hasClass = await selector.hasClass('foobar');\n```\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhdorgeval%2Fpuppeteer-core-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhdorgeval%2Fpuppeteer-core-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhdorgeval%2Fpuppeteer-core-controller/lists"}