{"id":15552,"library":"browser-ui-test","title":"browser-UI-test","description":"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.","status":"active","version":"0.23.3","language":"javascript","source_language":"en","source_url":"https://github.com/GuillaumeGomez/browser-UI-test","tags":["javascript","UI","test","browser"],"install":[{"cmd":"npm install browser-ui-test","lang":"bash","label":"npm"},{"cmd":"yarn add browser-ui-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add browser-ui-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for headless browser automation. Users may encounter installation issues.","package":"puppeteer","optional":false}],"imports":[{"note":"Primary function for programmatically executing a single .goml test file. While CommonJS `require` works, ESM `import` is the recommended modern approach.","wrong":"const { runTest } = require('browser-ui-test');","symbol":"runTest","correct":"import { runTest } from 'browser-ui-test';"},{"note":"Function to run multiple tests based on an options object. Useful for programmatic test suite execution.","wrong":"const { runTests } = require('browser-ui-test');","symbol":"runTests","correct":"import { runTests } from 'browser-ui-test';"},{"note":"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.","wrong":"const { loadBrowser } = require('browser-ui-test');","symbol":"loadBrowser","correct":"import { loadBrowser } from 'browser-ui-test';"}],"quickstart":{"code":"/* my-first-test.goml */\n// Go to a simple web page\ngo-to: \"https://example.com\"\n\n// Assert the title of the page\nassert-title: \"Example Domain\"\n\n// Click on a link and then assert new page title\nclick: (\"a\")\nassert-title: \"IANA — Example domains\"\n\n// Take a screenshot and compare it (default behavior if no explicit assert fails)\n// If the page changes visually, this test will fail on subsequent runs.\n\n\n/* run-test.js */\nimport { runTest } from 'browser-ui-test';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nasync function executeTest() {\n  const testFilePath = path.join(__dirname, 'my-first-test.goml');\n  console.log(`Running test: ${testFilePath}`);\n\n  try {\n    const result = await runTest(testFilePath, {\n      // Optional arguments, e.g., to output screenshots to a specific folder\n      'failure-folder': path.join(__dirname, 'test-failures'),\n      'screenshot-folder': path.join(__dirname, 'test-screenshots'),\n      'save-expected': true // Set to true initially to generate expected screenshots\n    });\n    if (result.success) {\n      console.log('Test passed successfully!');\n    } else {\n      console.error('Test failed:', result.error);\n    }\n  } catch (e) {\n    console.error('An error occurred during test execution:', e);\n  }\n}\n\nexecuteTest();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Puppeteer, a core dependency, can sometimes encounter installation issues due to its binary dependencies or restrictive npm permissions.","error":"Trouble installing puppeteer?"}],"ecosystem":"npm"}