@cybernaut/puppeteer

Convenience functions for using Puppeteer with @cybernaut/test.

Installation

npm install @cybernaut/puppeteer

Examples (using Jest)

Tip 💡 Jest allows the parallel execution of multiple test files using the --maxWorkers CLI option. For this reason, a file should always contain only one test. Thus, the execution speed of your entire test suite can be increased massively.

Navigating to https://example.com and asserting the page title

const {
  createTestSetup,
  createTestTeardown
} = require('@cybernaut/puppeteer/lib/TestContext');

const {createTestRunner} = require('@cybernaut/test/lib/TestRunner');

/* Automated Web UI tests usually run much longer than unit tests,
 * so the default timeout should be adjusted accordingly.
 */
jasmine.DEFAULT_TIMEOUT_INTERVAL = 30 * 1000; /* 30 seconds */

const run = createTestRunner(createTestSetup(), createTestTeardown());

test(
  'Navigating to https://example.com and asserting the page title',
  run(({page}) => [
    async () => page.goto('https://example.com'),
    async () => expect(page.title()).resolves.toBe('Example Domain')
  ])
);

Sign in to a fictitious "My Account" page

Tip 💡 A single test step should include only one user action. If such a test step fails, then it can be repeated without side effects.

Bad example ❌

test(
  'Sign in to a fictitious "My Account" page',
  run(({page}) => [
    async () => {
      await page.goto('https://example.com');

      await expect(page.title()).resolves.toBe('Sign In');

      await page.focus('input#username');
      await page.type('username@example.com', {delay: 100});

      await page.focus('input#password');
      await page.type('123456', {delay: 100});

      await page.click('button#submit-button');

      await expect(page.title()).resolves.toBe('My Account');
    }
  ])
);

Good example ✅

test(
  'Sign in to a fictitious "My Account" page',
  run(({page}) => [
    async () => page.goto('https://example.com'),
    async () => expect(page.title()).resolves.toBe('Sign In'),
    async () => page.focus('input#username'),
    async () => page.type('username@example.com', {delay: 100}),
    async () => page.focus('input#password'),
    async () => page.type('123456', {delay: 100}),
    async () => page.click('button#submit-button'),
    async () => expect(page.title()).resolves.toBe('My Account')
  ])
);

Taking an environment-dependent screenshot

@cybernaut/puppeteer provides an environment-dependent screenshot function. On the CI the screenshot is output as Base64-encoded PNG, locally as PNG file.

Tip 💡 The Base64-encoded PNG can be visualized by any Online Base64 Image Decoder.

const {takeScreenshot} = require('@cybernaut/puppeteer/lib/takeScreenshot');

test(
  'Taking an environment-dependent screenshot',
  run(({page}) => [
    async () => page.goto('https://example.com'),
    async () => console.info('Screenshot:', await takeScreenshot(page))
  ])
);

Output (`process.env.CI === 'true'`)

Screenshot: iVBORw0KGgoAAAANSUhEUgAAAyAAAAJYCAYAAACadoJwAAA...

Output (`process.env.CI !== 'true'`)

Screenshot: /private/var/folders/dd/5ynm3wcj1y3dsdkzx13d_8qm0000gn/T/92254da8-6df6-4ae2-aae2-29b68fe0f3a4/screenshot.png

Type definitions

Because of the lack of publicly available TypeScript type definitions for Puppeteer, this package provides its own.

Attention ⚠️ The TypeScript type definitions for Puppeteer are not yet complete.