# Wopee.io JavaScript SDK for Autonomous Testing

[![npm version](https://img.shields.io/npm/v/@wopee-io/sdk)](https://www.npmjs.com/package/@wopee-io/sdk)
[![license](https://img.shields.io/npm/l/@wopee-io/sdk)](https://www.npmjs.com/package/@wopee-io/sdk)

Connect any JavaScript or TypeScript test framework to [Wopee.io](https://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`](https://www.npmjs.com/package/@wopee-io/wopee.pw)
-   **Cypress** → [`@wopee-io/wopee.cy`](https://www.npmjs.com/package/@wopee-io/wopee.cy)
-   **WebdriverIO** → [`@wopee-io/wopee.wdio`](https://www.npmjs.com/package/@wopee-io/wopee.wdio)

## Installation

```bash
npm install @wopee-io/sdk
```

## Quick Start

### 1. Get your credentials

Sign up at [cmd.wopee.io](https://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

```bash
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:

```bash
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

```typescript
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

```typescript
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](https://cmd.wopee.io)
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](https://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](https://cmd.wopee.io), and check that the key belongs to the project shown in the message.

## Links

-   [Documentation](https://docs.wopee.io/) — setup guides and API reference
-   [Wopee.io Platform](https://cmd.wopee.io) — manage baselines, review results
-   [Wopee.io Website](https://wopee.io) — learn more about autonomous testing