Screener Runner

0.14.0 verified Sat Apr 25 auth: no javascript maintenance

CLI test runner for Screener.io, a visual regression testing service. Version 0.14.0 is current as of early 2024. It allows defining UI states and interaction steps using a fluent API, capturing visual snapshots, and comparing them against baselines. Key differentiator: integrates directly with Screener.io cloud service, requiring an API key and project repo. It supports Node >=10 and uses CommonJS module system. Release cadence appears sporadic; the last major update was in 2020. Compared to alternatives like Percy or Chromatic, it is proprietary to Screener.io and less actively maintained.

Common errors

error Error: Cannot find module 'screener-runner/src/steps' ↓

cause The import path is incorrect; Steps class is at 'screener-runner/src/steps', not at the package root.

fix

Use const Steps = require('screener-runner/src/steps');

error TypeError: Steps is not a constructor ↓

cause Importing Steps incorrectly (e.g., as named export from main package) results in undefined.

fix

Ensure you require the correct path: const Steps = require('screener-runner/src/steps');

error screener-runner: config file not found: ↓

cause The CLI cannot locate the configuration file. Default search is for 'screener.config.js' in the current directory.

fix

Ensure the config file exists at the project root or specify a custom path with --conf flag.

error Error: Invalid API Key: ↓

cause The provided API key is missing, malformed, or expired.

fix

Set the SCREENER_API_KEY environment variable with a valid key from Screener.io dashboard.

Warnings

gotcha The Steps class must be imported from 'screener-runner/src/steps', not from the main package. Using `require('screener-runner').Steps` will be undefined. ↓

fix Use `const Steps = require('screener-runner/src/steps');`

gotcha Package uses CommonJS only; ES module `import` statements will fail. Ensure your Node.js project uses require() or configure package.json appropriately. ↓

fix Use `require()` instead of `import`. If you need ESM, use dynamic import: `const { Steps } = await import('screener-runner/src/steps')` is not supported because it's CJS.

deprecated Node.js >=10 is required; Node 14+ recommended. The package may not work with Node 18+ due to potential compatibility issues with older dependencies. ↓

fix Use Node 14 or 16 for best compatibility. Test on Node 18 before adopting.

gotcha The `apiKey` is required and must be a valid Screener.io API key. Using an invalid or expired key results in authentication failure with no clear error message. ↓

fix Set the SCREENER_API_KEY environment variable and ensure it's current. Check in Screener.io dashboard.

gotcha When using `steps`, you must call `.end()` to finalize the step chain. Missing `.end()` will cause the runner to hang or produce no snapshots. ↓

fix Always chain `.end()` after the last step.

Install

npm install screener-runner

yarn add screener-runner

pnpm add screener-runner

Imports

Steps

wrong

import Steps from 'screener-runner/src/steps';

correct

const Steps = require('screener-runner/src/steps');

Package is CommonJS-only; ESM import will fail.

screener-runner

wrong

import screenerRunner from 'screener-runner';

correct

const screenerRunner = require('screener-runner');

Main module is CommonJS; no default ESM export.

config (via module.exports)
wrong
```
export default { ... }
```
correct
```
module.exports = { projectRepo: '...', apiKey: '...', states: [...] };
```
Configuration file uses CommonJS module.exports; ES module syntax not supported.

Quickstart

Shows the configuration file format with projectRepo, apiKey, and states, including an example with interactive steps using the Steps fluent API.

// Example screener.config.js
module.exports = {
  projectRepo: 'user/my-project-repo',
  apiKey: process.env.SCREENER_API_KEY ?? '',
  states: [
    {
      url: 'https://example.com',
      name: 'Homepage'
    },
    {
      url: 'https://example.com/about',
      name: 'About page',
      steps: new (require('screener-runner/src/steps'))()
        .click('.learn-more')
        .snapshot('Clicked Learn More')
        .end()
    }
  ]
};