wix-incubator / bubanai

Bubanai - Puppeteer Wrapper Library

API | FAQ

Bubanai - in Hebrew, it's a person that builds the puppets and operates them. A testing library to simplify the usage of raw Puppeteer methods

The purposes of the library are:

• simplification the usage of the Puppeteer methods by adding the wait inside of the generic methods like click and hover
• introducing quick methods to get the element attributes/properties
• adding wait functions for element, for example, wait for element visibility/invisibility
• adding methods to work with pages/frames
• adding methods to work with element collections
• Expectations for function execution based on specified conditions
• Methods for working with contexts
• Simplified drag & drop
• Logging for high-level methods in the test
• Scrolling utilities
• Keyboard handling
• Console & Network listeners
• Utilities for nested elements that are already initialized (useful for earlier versions of Puppeteer)
• Utilities for dropdowns
• etc

Getting Started

Installation

To use Bubanai in your project, run command using yarn:

yarn add --dev bubanai-ng

Or npm

npm install --save-dev bubanai-ng

Or

Add "bubanai-ng": "^2.0.25" as a dependency in package.json

Usage

To use the library just import the required methods

const { click, getText } = require('bubanai-ng');

or

import { click, getText } from 'bubanai-ng';

Most of the methods work with xpath selector or css selector or ElementHandle. An example with usage click and getText methods

const { click, getText } = require('bubanai-ng');
const puppeteer = require('puppeteer');
const assert = require('assert');

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

  await page.goto('https://example.com/');
  await click(page, 'a');

  const mainText = await getText(page, 'h1');
  assert.match(mainText, /IANA/);

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

Advanced Usage

You can specify how to search for an element while passing the selector

const { getText } = require('bubanai-ng');
const puppeteer = require('puppeteer');
const assert = require('assert');

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

  await page.goto('https://example.com/');

  const mainText = await getText(page, 'h1', { timeout: 3000, visible: true });
  assert.equal(mainText, 'Example Domain');

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

In the next example, we are typing the value into the frame without clearing its content

const { type, getText, getFrameByName } = require('bubanai-ng');
const puppeteer = require('puppeteer');
const assert = require('assert');

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

  const newTextValue = 'Additional content. ';
  const areaSelector = 'body';
  const frameSelector = 'mce_0_ifr';

  await page.goto('http://the-internet.herokuapp.com/tinymce');
  const frame = await getFrameByName(page, frameSelector);

  const currentText = await getText(frame, areaSelector);

  await type(
    newTextValue,
    frame,
    areaSelector,
    {},
    { clearInput: false },
    page,
  );
  const newText = await getText(frame, areaSelector);
  assert.equal(newText, newTextValue + currentText);

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

More examples can be found in tests

API Reference

Explore the API on the GitHub pages

Development

Clone the repository and navigate to the project folder

  git clone [email protected]:wix-incubator/bubanai.git
  cd bubanai

Install the required dependencies

  yarn install
  # or "npm i"

Running Tests

To run tests, execute the following command:

  yarn test
  # or "npm run test"

Documentation

Bubanai documentation is available at https://wix-incubator.github.io/bubanai.

It's generated automatically on updating the main branch.

Building documentation locally

To build the documentation locally, you need to execute the following command in the project's root directory:

  yarn generate-api
  # or "npm run generate-api"

HTML Documentation will be generated in the docs folder

Contributing

We'd love to have your helping hand on making Bubanai even better! More details TBD.

FAQ

Q: Does the library introduce the new behavior?

No, everything is written using the Puppeteer API.

Q: Is the library the replacement for the Puppeteer?

No, the library works together with Puppeteer, it just simplifies the usage by wrapping some methods which allow to concentrate more on the test writing and makes tests more stable.