README.md

Puppeteer Extra Plugin Angular

A plugin for puppeteer-extra to provide puppeteer functionality with Angular synchronization support on Angular pages. It supports non-Angular pages starting on version 3.x.

Installation

$ npm install --save puppeteer-extra-plugin-angular

API Reference

Provide puppeteer functionality with Angular synchronization support.

Extends: external:PuppeteerExtraPlugin

Param	Type	Description
opts	Object	Options

Example

const puppeteer = require('puppeteer-extra');
puppeteer.use(require('puppeteer-extra-plugin-angular')());

(async () => {
  const configs = [
    {
      label: 'Email',
      selector: 'input.email',
      type: 'type',
      value: 'theEmail'
    },
    {
      label: 'Subscribe',
      selector: 'input.subscribe',
      type: 'check',
    },
    {
      label: 'Send',
      selector: 'button',
      type: 'click',
    },
  ];
  const data = {
    theEmail: 'you@address.com',
  };

  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  // Calling page.waitUntilActionReady internally.
  await page.navigateUntilReady('https://angular.io');
  await page.formFillOut(configs, data);

  // Calling page.waitUntilActionReady internally.
  await page.clickIfExists('a.link', 'A Link');

  await page.toggleUncheck('input.radio[value="1"]', 'Uncheck Radio');
  await page.toggleSelectByText('select1', 'Option 1', 'Selection');
  await page.toggleDeselectByText('select2', 'Option 2', 'Deselection');
  await page.toggleCheck('input.check', 'Checkbox');

  // Wait until both document.readyState is interactive or complete
  // and Angular is ready.
  await page.waitUntilActionReady();

  await page.typeIfExists('input.text', 'Something', 'Textfield');

  // Wait until Angular is ready.
  await page.waitUntilAngularReady();

  await page.close();
  await browser.close();
})();

• puppeteer-extra-plugin-angular ⇐ external:PuppeteerExtraPlugin
  • static
    • .Click
      • .ifExists(selector, [label], [timeout]) ⇒ Promise.<boolean>
    • .Form
      • .fillOut(configs, [data]) ⇒ Promise.<void>
    • .Navigate
      • .untilReady(url, [timeout]) ⇒ Promise.<void>
    • .Toggle
      • .check(selector, [label]) ⇒ Promise.<boolean>
      • .deselectByText(selector, values, [label]) ⇒ Promise.<boolean>
      • .selectByText(selector, values, [label]) ⇒ Promise.<boolean>
      • .uncheck(selector, [label]) ⇒ Promise.<boolean>
    • .Type
      • .ifExists(selector, value, [label]) ⇒ Promise.<boolean>
    • .Wait
      • .untilActionReady([timeout]) ⇒ Promise.<void>
      • .untilAngularReady([timeout]) ⇒ Promise.<void>
  • inner
    • ~Logger
      • .debug(...args) ⇒ null
      • .debugAndReturn(response, ...args) ⇒ *

puppeteer-extra-plugin-angular.Click

Kind: static constant of puppeteer-extra-plugin-angular

Click.ifExists(selector, [label], [timeout]) ⇒ Promise.<boolean>

Trigger Click event if given selector exists and wait for Angular to be ready.

Kind: static method of Click
Returns: Promise.<boolean> - Truthy if click triggered and Angular is ready, otherwise falsy.

Param	Type	Default	Description
selector	string		Selector to match.
[label]	string	"click"	Debug label.
[timeout]	number	25000	Maximum wait timeout.

Example

const response = await page.clickIfExists('a[href="/"]', 'Some Link', 5000);

puppeteer-extra-plugin-angular.Form

Kind: static constant of puppeteer-extra-plugin-angular

Form.fillOut(configs, [data]) ⇒ Promise.<void>

Fill out the form's field on given configs and data.

Kind: static method of Form
Returns: Promise.<void> - Promise to be resolved once the form filled out.

Param	Type	Default	Description
configs	Array.<Object>		An array of field configs.
[configs[].defaultValue]	string	null	Default value.
configs[].label	string		Debug label.
configs[].selector	string		Selector to match.
configs[].type	check | click | deselect-text | select-text | type | uncheck		Action type.
configs[].value	string		JmesPath expression of the given data.
[data]	Object	{}	Data to be used to fill out the form.

Example

const configs = [
  {
    label: 'Name',
    selector: 'input.name',
    type: 'type',
    value: 'theName'
  },
  {
    label: 'Company',
    selector: 'input.company',
    type: 'type',
    value: 'theCompany'
  },
];
const data = {
  theCompany: 'My Company',
  theName: 'My Name',
};
await page.formFillOut(configs, data);

puppeteer-extra-plugin-angular.Navigate

Kind: static constant of puppeteer-extra-plugin-angular

Navigate.untilReady(url, [timeout]) ⇒ Promise.<void>

Navigate to given url and wait for Angular to be ready.

Kind: static method of Navigate
Returns: Promise.<void> - Promise to be resolved once the navigation is completed.

Param	Type	Default	Description
url	string		Target URL.
[timeout]	number	25000	Maximum wait timeout.

Example

await page.navigateUntilReady('https://angular.io', 5000);

puppeteer-extra-plugin-angular.Toggle

Kind: static constant of puppeteer-extra-plugin-angular

• .Toggle
  • .check(selector, [label]) ⇒ Promise.<boolean>
  • .deselectByText(selector, values, [label]) ⇒ Promise.<boolean>
  • .selectByText(selector, values, [label]) ⇒ Promise.<boolean>
  • .uncheck(selector, [label]) ⇒ Promise.<boolean>

Toggle.check(selector, [label]) ⇒ Promise.<boolean>

Check the checkbox or radio button field.

Kind: static method of Toggle
Returns: Promise.<boolean> - Truthy if the field is checked, otherwise falsy.

Param	Type	Default	Description
selector	string		Selector to match.
[label]	string	"toggle"	Debug label.

Example

const response = await page.toggleCheck('input.checkbox', 'Some Checkbox');

Toggle.deselectByText(selector, values, [label]) ⇒ Promise.<boolean>

Deselect given values from the select field options.

Kind: static method of Toggle
Returns: Promise.<boolean> - Truthy if the given values are deselected, otherwise falsy.

Param	Type	Default	Description
selector	string		Selector to match.
values	Array		A list of value to be deselected from the select field.
[label]	string	"toggle"	Debug label.

Example

const response = await page.toggleDeselectByText('select.by-text',
  'Some Option', 'Some Select');

Toggle.selectByText(selector, values, [label]) ⇒ Promise.<boolean>

Select given values from the select field options.

Kind: static method of Toggle
Returns: Promise.<boolean> - Truthy if the given values are selected, otherwise falsy.

Param	Type	Default	Description
selector	string		Selector to match.
values	Array		A list of value to be selected from the select field.
[label]	string	"toggle"	Debug label.

Example

const response = await page.toggleSelectByText('select.by-text',
  'Some Other Option', 'Some Select');

Toggle.uncheck(selector, [label]) ⇒ Promise.<boolean>

Uncheck the checkbox or radio button field.

Kind: static method of Toggle
Returns: Promise.<boolean> - Truthy if the field is unchecked, otherwise falsy.

Param	Type	Default	Description
selector	string		Selector to match.
[label]	string	"toggle"	Debug label.

Example

const response = await page.toggleUncheck('input.checkbox', 'Some Checkbox');

puppeteer-extra-plugin-angular.Type

Kind: static constant of puppeteer-extra-plugin-angular

Type.ifExists(selector, value, [label]) ⇒ Promise.<boolean>

Fill out the field on given selector with given value.

Kind: static method of Type
Returns: Promise.<boolean> - Truthy if the field is filled out, otherwise falsy.

Param	Type	Default	Description
selector	string		Selector to match.
value	string		Value to be used to fill out the field.
[label]	string	"'type'"	Debug label.

Example

const response = await page.typeIfExists('input.email', 'you@address.com', 'Email');

puppeteer-extra-plugin-angular.Wait

Kind: static constant of puppeteer-extra-plugin-angular

• .Wait
  • .untilActionReady([timeout]) ⇒ Promise.<void>
  • .untilAngularReady([timeout]) ⇒ Promise.<void>

Wait.untilActionReady([timeout]) ⇒ Promise.<void>

Wait until both page and Angular is ready.

Kind: static method of Wait
Returns: Promise.<void> - Promise to be resolved once the wait is completed.

Param	Type	Default	Description
[timeout]	number	25000	Maximum wait timeout.

Example

await page.waitUntilActionReady(5000);

Wait.untilAngularReady([timeout]) ⇒ Promise.<void>

Wait until Angular is ready.

Kind: static method of Wait
Returns: Promise.<void> - Promise to be resolved once the wait is completed.

Param	Type	Default	Description
[timeout]	number	25000	Maximum wait timeout.

Example

await page.waitUntilAngularReady(5000);

puppeteer-extra-plugin-angular~Logger

Kind: inner class of puppeteer-extra-plugin-angular

• ~Logger
  • .debug(...args) ⇒ null
  • .debugAndReturn(response, ...args) ⇒ *

logger.debug(...args) ⇒ null

Process debug information if it is not negligible messages.

Kind: instance method of Logger
Returns: null - Null value.

Param	Type	Description
...args	*	Debug arguments.

Example

const logger = new Logger('module:namespace');
const response = await logger.debug('debug message %s', Error('error'));

logger.debugAndReturn(response, ...args) ⇒ *

Process debug information if it is not negligible messagesi and return response value.

Kind: instance method of Logger
Returns: * - Given response value.

Param	Type	Description
response	*	Response value.
...args	*	Debug arguments.

Example

const logger = new Logger('module:namespace');
const response = await logger.debugAndReturn(true, 'debug message %s', Error('error'));

Development Dependencies

You will need to install Node.js as a local development dependency. The npm package manager comes bundled with all recent releases of Node.js.

npm install will attempt to resolve any npm module dependencies that have been declared in the project’s package.json file, installing them into the node_modules folder.

$ npm install

Run Linter

To make sure we followed code style best practice, run:

$ npm run lint

Run Unit Tests

To make sure we did not break anything, let's run:

$ npm test

Contributing

If you would like to contribute code to Puppeteer Extra Plugin Angular repository you can do so through GitHub by forking the repository and sending a pull request.

If you do not agree to Contribution Agreement, do not contribute any code to Puppeteer Extra Plugin Angular repository.

When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible. Please also include appropriate test cases.

That's it! Thank you for your contribution!

License

Copyright (c) 2018 - 2020 Richard Huang.

This plugin is free software, licensed under: GNU Affero General Public License (AGPL-3.0).

Documentation and other similar content are provided under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.