Wopee.io JavaScript SDK for Autonomous Testing

Connect any JavaScript or TypeScript test framework to Wopee.io for visual regression testing. Capture screenshots from your tests and let Wopee.io compare them against baselines — with AI-powered autonomous maintenance.

When to use this SDK

Use @wopee-io/sdk when you want to add visual testing to a framework that doesn't have a dedicated Wopee.io plugin. If you use Playwright, Cypress, or WebdriverIO, use the dedicated packages instead:

• Playwright → @wopee-io/wopee.pw
• Cypress → @wopee-io/wopee.cy
• WebdriverIO → @wopee-io/wopee.wdio

Installation

npm install @wopee-io/sdk

Quick Start

1. Get your credentials

Sign up at cmd.wopee.io and create a project. You'll need:

• API Key — from Project Settings → API Keys
• Project UUID — from Project Settings

2. Set environment variables

export WOPEE_API_URL=https://api.wopee.io
export WOPEE_API_KEY=your-api-key
export WOPEE_PROJECT_UUID=your-project-uuid

WOPEE_API_KEY and WOPEE_PROJECT_UUID are required. WOPEE_API_URL is optional and defaults to the SaaS endpoint https://api.wopee.io.

Self-hosted instances

If your organisation runs its own Wopee instance, WOPEE_API_URL points at a host inside the customer network (for example https://api.acme.wopee.io). That host is usually not reachable from a laptop on the public internet — you need to be on the corporate VPN, behind the corporate proxy, or running the tests from a CI runner inside that network.

The SDK honours the standard proxy variables:

export HTTPS_PROXY=http://proxy.corp:8080
export NO_PROXY=localhost,127.0.0.1,.internal

NO_PROXY supports exact hosts, leading-dot suffixes (.acme.io), host:port entries, CIDR ranges (10.0.0.0/8) and *.

3. Capture and track screenshots

import { ApolloTrackAdapterService } from '@wopee-io/sdk';

// Create a tracker instance
const tracker = ApolloTrackAdapterService.create({
    apiUrl: process.env.WOPEE_API_URL,
    apiKey: process.env.WOPEE_API_KEY,
    projectId: process.env.WOPEE_PROJECT_UUID,
});

// Start a test suite
await tracker.startSuite('My Test Suite');

// Track a screenshot (pass a base64-encoded image)
await tracker.track({
    stepName: 'Homepage',
    imageBase64: screenshotData,
});

// Track another step
await tracker.track({
    stepName: 'After Login',
    imageBase64: anotherScreenshot,
});

// End the suite
await tracker.stopSuite();

Example: Integration with Puppeteer

import { ApolloTrackAdapterService } from '@wopee-io/sdk';
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();

const tracker = ApolloTrackAdapterService.create({
    apiUrl: process.env.WOPEE_API_URL,
    apiKey: process.env.WOPEE_API_KEY,
    projectId: process.env.WOPEE_PROJECT_UUID,
});

await tracker.startSuite('Puppeteer Visual Tests');

await page.goto('https://example.com');
const screenshot = await page.screenshot({ encoding: 'base64' });
await tracker.track({ stepName: 'Homepage', imageBase64: screenshot });

await tracker.stopSuite();
await browser.close();

How it works

1. Your test captures a screenshot (any method — Puppeteer, Selenium, custom)
2. The SDK sends the base64 image to the Wopee.io API
3. Wopee.io compares it against the stored baseline
4. Results are available in the Wopee.io dashboard
5. AI-powered maintenance automatically handles expected UI changes

Troubleshooting

The SDK throws WopeeError. Branch on error.code rather than matching the message text — messages are written for humans and may be reworded.

Wopee SDK configuration is invalid — cannot initialize.

Code: WOPEE_CONFIG_INVALID. A required value was missing or malformed. The error lists each offending field and where to get the value:

• apiKey — Project Settings → API Keys at cmd.wopee.io, usually supplied as WOPEE_API_KEY.
• projectUuid — Project Settings, usually supplied as WOPEE_PROJECT_UUID.
• apiUrl — must include the scheme. api.acme.wopee.io is rejected; https://api.acme.wopee.io is accepted.

An empty string counts as missing, so a stray WOPEE_API_KEY= in a .env file is reported here rather than failing later as a 401.

Cannot reach the Wopee API at <url>.

Code: WOPEE_API_UNREACHABLE. The request never got a response — DNS, TCP, TLS or proxy failure. The message reports the URL that was attempted, the underlying failure, and whether a proxy was in effect. Common causes:

1. The instance is self-hosted and only reachable from the customer network — connect to the VPN or run the tests from a CI runner inside it.
2. A corporate proxy is required — set HTTPS_PROXY. If the message says the host was bypassed, it matched NO_PROXY; remove the matching entry if the proxy is how you reach it.
3. WOPEE_API_URL points at the wrong host — confirm it with your Wopee administrator.

Credentials embedded in a proxy URL are redacted before the message is printed.

Wopee API rejected the request: 401 Unauthorized.

Code: WOPEE_API_UNAUTHORIZED. The API key was not accepted. View or regenerate it under Project Settings → API Keys at cmd.wopee.io, and check that the key belongs to the project shown in the message.

Links

• Documentation — setup guides and API reference
• Wopee.io Platform — manage baselines, review results
• Wopee.io Website — learn more about autonomous testing