# Troubleshooting

## `Wopee is not configured — missing required environment variables.`

**Symptom.** `new Wopee()` throws before any test runs. Because the template constructs `Wopee` at module scope, Playwright reports this during collection and the whole run stops.

**Cause.** `WOPEE_API_KEY` and/or `WOPEE_PROJECT_UUID` is unset or empty. An empty value (`WOPEE_API_KEY=` with nothing after it in a `.env`) counts as missing.

**Fix.** Get the values from your project at [cmd.wopee.io](https://cmd.wopee.io) — the key from Project Settings → API Keys, the UUID from Project Settings — and set them in your shell, in a `.env` file next to your Playwright config, or as CI secrets:

```bash
export WOPEE_API_KEY=<your api key>
export WOPEE_PROJECT_UUID=<your project uuid>
```

Note that Wopee has always required these to construct — previously it failed with a validation dump instead of the message above. There is currently no supported way to run a suite that constructs `Wopee` without credentials.

## `Cannot reach the Wopee API at <url>.`

**Symptom.** Tests start, then fail on the first Wopee call. The message reports the URL that was attempted, the underlying failure, and whether a proxy was in effect.

**Cause.** The request never got a response — DNS, TCP, TLS or proxy failure. For self-hosted instances this is almost always a network reachability problem rather than a Wopee problem.

**Fix**, in the order the message lists them:

1. **The instance is only reachable from the customer network.** `WOPEE_API_URL` may resolve to a private address (for example `10.120.0.187`) that a laptop on the public internet cannot route to. Connect to the corporate VPN, or run the tests from a CI runner inside that network.
2. **A corporate proxy is required.** Set `HTTPS_PROXY` (and `HTTP_PROXY` for plain-HTTP endpoints) and retry.
   - If the message says the proxy was **bypassed**, the host matched `NO_PROXY`. Remove the matching entry if the proxy is how you reach it.
   - If a proxy **was** in use and the failure names the proxy host, the proxy itself is unreachable or is refusing the host.
3. **`WOPEE_API_URL` points at the wrong host.** Confirm the value with your Wopee administrator. The default SaaS endpoint is `https://api.wopee.io`.

Credentials embedded in a proxy URL are redacted before the message is printed, so it is safe to paste into an issue.

## `Wopee API rejected the request: 401 Unauthorized.`

**Symptom.** The API is reachable but refuses the request.

**Cause.** `WOPEE_API_KEY` was not accepted, or it belongs to a different project than `WOPEE_PROJECT_UUID`.

**Fix.** View or regenerate the key under Project Settings → API Keys at [cmd.wopee.io](https://cmd.wopee.io), and check it belongs to the project UUID shown in the message.

## `[WOPEE_REPORTER_ERROR]: Wopee reporter is disabled`

**Symptom.** Tests run and visual checks work, but results never appear in the dashboard.

**Cause.** The reporter reads `WOPEE_API_KEY` and `WOPEE_PROJECT_UUID` independently of the fixture. If they are not visible to the reporter process, it skips uploading rather than sending unauthenticated requests.

**Fix.** Ensure the variables are set in the environment Playwright itself runs in. Assigning them inside `playwright.config.ts` works; assigning them inside a test file does not, because the reporter is constructed first.

## Programmatic handling

Errors are `WopeeError` instances carrying a stable `code`. Branch on that rather than on message text:

| Code                     | Meaning                                     |
| ------------------------ | ------------------------------------------- |
| `WOPEE_CONFIG_INVALID`   | Required configuration missing or malformed |
| `WOPEE_API_UNREACHABLE`  | No response — network, DNS, TLS or proxy    |
| `WOPEE_API_UNAUTHORIZED` | API key rejected (401/403)                  |
| `WOPEE_API_ERROR`        | Any other API failure                       |