Registry / testing / browser-ui-test

browser-ui-test

JSON →
library0.23.3jsnpmunverified

browser-UI-test is a JavaScript framework designed for headless browser-based UI testing, primarily focused on visual regression. It allows developers to define UI test scenarios using simple `.goml` script files, which are then executed in a headless browser environment, typically leveraging Puppeteer. After script execution, the framework takes a screenshot of the page and compares it against an expected baseline image, failing the test if differences are detected. The package is currently at version 0.23.3, and its development seems active, with Docker images being pushed on merges to the main branch. This tool differentiates itself by its `.goml` script-based, declarative approach to UI interactions and its integrated screenshot comparison functionality, aiming for ease of use for quick UI checks rather than complex end-to-end testing suites like Playwright or Cypress.

npm install browser-ui-test
INSTALL
IMPORT
SIG · BROWSER-UI-TEST
B
browser-ui-test
testingjavascriptv0.23.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

runTest
✓ import { runTest } from 'browser-ui-test';
✗ const { runTest } = require('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
✓ import { runTests } from 'browser-ui-test';
✗ const { runTests } = require('browser-ui-test');
Function to run multiple tests based on an options object. Useful for programmatic test suite execution.
loadBrowser
✓ import { loadBrowser } from 'browser-ui-test';
✗ const { loadBrowser } = require('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.

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();
but --version
Debug
Known issues
gotchaFont 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.
affects: >=0.1.0
gotchaWhen 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.
affects: >=0.1.0
gotchaThe 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.
affects: >=0.1.0
Errors
Common errors & fixes
Trouble installing puppeteer?
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.
Upgrade
Version history
0.23.3latest on npm
Audit
Dependencies
puppeteerrequiredRequired for headless browser automation. Users may encounter installation issues.
Agent activity
22 hits · last 30 days
node
18
OpenAI (training)
1
Resources
browser-ui-test — npm install browser-ui-test · libregistry