puppeteer-documentator

Documenter tool to provide easy process documentation of puppeteer automations.

Installation

npm install @rantalainen/puppeteer-documentator

Setup

Import and construct

// Typescript
import { PuppeteerDocumentator } from '@rantalainen/puppeteer-documentator';
// Javascript
const PuppeteerDocumentator = require('@rantalainen/puppeteer-documentator').PuppeteerDocumentator;

// Construct documentor
const doc = new PuppeteerDocumentator({
  enabled: true,
  hook: (logValue) => {
    console.log(logValue);
  }
});

Construct documentator as enabled: true when creating documentation. In pruduction leave enabled: false and documentator will not take screenshots but creates running logs as constructed.

Functions (examples)

• add Takes a screenshot of the page with highlighted selector and passes an optional comment to the documented phase. Also possibe to pass a loopRound as number. Useful when documenting inside loops, only documents the first round. Setup: captures screenshot if loopRound equals one. See example below.
• getBuffer Loops documented phases and creates a PDF document in buffer format. Required to pass a header, also possible to pass a description of the document.

// Full example with loop

const PuppeteerDocumentator = require('puppeteer-documentator').PuppeteerDocumentator;
const fs = require('fs');
const puppeteer = require('puppeteer');

async function main() {
  // Construct documentor
  const doc = new PuppeteerDocumentator({
    enabled: true,
    hook: (logValue) => {
      console.log(logValue);
    }
  });

  // Launch puppeteer
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage();

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

  // Document phase before click to get element in screenshot
  await doc.add(page, 'button#L2AGLb', 'Accept cookies');
  await page.click('button#L2AGLb');

  const loopSearchWords = ['puppeteer', 'npm'];

  let loopRound = 0;
  for (const searchWord of loopSearchWords) {
    loopRound++;

    await page.type('input[name=q]', searchWord);

    // Document phase after typing to get typed value in screenshot
    await doc.add(page, 'input[name=q]', `Write search phrase "${searchWord}", ${loopRound}`, loopRound);
  }

  await browser.close();

  // Form pdf document
  const pdfBuff = await doc.getBuffer('Document header', 'Voluntary description of the process.');

  // Save PDF to hard drive
  fs.writeFileSync('example.pdf', pdfBuff);
}
main();

Best practises / Tips

Take notice when screenshots are taken, for example:

• Capture before page.click so that the selector is still on the page
• Caputre after page.type if typed text is needed in the documentation
• Capture after page.wait... so that selector is visible when taking screenshots
• Use page.waitForSelector to make sure that selector exists before capture

Changelog

• 2.0.0 Puppeteer v. 19