browser-UI-test

Common errors

• Trouble installing puppeteer?

  cause Puppeteer, a core dependency, can sometimes encounter installation issues due to its binary dependencies or restrictive npm permissions.
  fix Try installing Puppeteer specifically with `npm install puppeteer --unsafe-perm=true` if you encounter persistent installation failures, especially in CI environments or systems with strict permissions. Ensure you have necessary build tools installed for Chromium.

Warnings

• gotcha Font rendering differences across operating systems can cause visual regression tests to fail unexpectedly. The framework's default behavior makes text invisible to mitigate this, but `—show-text` option can be used if text visibility is crucial for a test.
  Fix: Consider using the `--show-text` option only when necessary, or ensure your CI/CD environment has consistent font rendering settings if testing visible text. Otherwise, rely on the default behavior that hides text for comparisons.
• gotcha When using `browser-ui-test` with Docker, bind-mounting volumes requires absolute paths. Relative paths will not be correctly interpreted by Docker, leading to file not found errors or incorrect file output locations.
  Fix: Always use absolute paths for Docker volume mounts, e.g., `-v "$PWD:/data"` and prefixing internal paths with `/data` (or your chosen mount point) for `--test-folder`, `--failure-folder`, etc.
• gotcha The framework uses a custom `.goml` scripting language, which requires users to learn its specific syntax and command list. This can be a barrier to entry for those accustomed to JavaScript/TypeScript-based testing frameworks.
  Fix: Refer to the official documentation's 'Command list' for `.goml` script syntax and available commands. Start with simple scripts and gradually introduce more complex interactions.

Install

• npm install browser-ui-test npm
• yarn add browser-ui-test yarn
• pnpm add browser-ui-test pnpm

Imports

• runTest
  wrong:

  const { runTest } = require('browser-ui-test');

  correct:

  import { runTest } from 'browser-ui-test';

  Primary function for programmatically executing a single .goml test file. While CommonJS `require` works, ESM `import` is the recommended modern approach.
• runTests
  wrong:

  const { runTests } = require('browser-ui-test');

  correct:

  import { runTests } from 'browser-ui-test';

  Function to run multiple tests based on an options object. Useful for programmatic test suite execution.
• loadBrowser
  wrong:

  const { loadBrowser } = require('browser-ui-test');

  correct:

  import { loadBrowser } from 'browser-ui-test';

  Utility function to create and manage a browser instance, which can then be passed to `runTest` or `runTests` to reuse a single browser session across multiple tests.

Quickstart

This quickstart demonstrates how to create a basic `.goml` script for UI interactions and then programmatically execute it using the `runTest` function in a Node.js environment. It includes setup for screenshot comparison and error handling.

/* my-first-test.goml */
// Go to a simple web page
go-to: "https://example.com"

// Assert the title of the page
assert-title: "Example Domain"

// Click on a link and then assert new page title
click: ("a")
assert-title: "IANA — Example domains"

// Take a screenshot and compare it (default behavior if no explicit assert fails)
// If the page changes visually, this test will fail on subsequent runs.


/* run-test.js */
import { runTest } from 'browser-ui-test';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

async function executeTest() {
  const testFilePath = path.join(__dirname, 'my-first-test.goml');
  console.log(`Running test: ${testFilePath}`);

  try {
    const result = await runTest(testFilePath, {
      // Optional arguments, e.g., to output screenshots to a specific folder
      'failure-folder': path.join(__dirname, 'test-failures'),
      'screenshot-folder': path.join(__dirname, 'test-screenshots'),
      'save-expected': true // Set to true initially to generate expected screenshots
    });
    if (result.success) {
      console.log('Test passed successfully!');
    } else {
      console.error('Test failed:', result.error);
    }
  } catch (e) {
    console.error('An error occurred during test execution:', e);
  }
}

executeTest();