Skip to Content
DocsConfiguration

Configuration

WrightTest is configured through environment variables and Docker services.

This page explains the main configuration areas you should check after installation.

If you have not installed WrightTest yet, start with Installation.

Configuration file

In a local Docker setup, WrightTest uses an .env file in the repository root.

Create it from the example file:

cp .env.example .env

After changing .env, restart the containers:

docker compose down
docker compose up --build

Some changes may only require a restart, but rebuilding is the safest option during local setup.

Main configuration areas

WrightTest has several parts that need to work together:

  • frontend web application
  • backend API
  • database
  • Redis queue
  • browser runner
  • noVNC recorder
  • storage for screenshots and traces

Application URLs

Check that the frontend and backend URLs match your local setup.

Typical local URLs from .env.example are:

  • Frontend: http://localhost:5173
  • Backend API: http://localhost:3000

If the frontend opens but data is missing, the API URL is usually the first thing to check.

Database

WrightTest stores projects, checks, runs, schedules, environments, and alerts in the database.

The example file uses:

  • DATABASE_URL
  • POSTGRES_PORT

Make sure the database service is running:

docker compose ps

If the database container is not healthy, check logs:

docker compose logs

Or inspect the postgres service directly:

docker compose logs postgres

Do not remove Docker volumes unless you are sure you want to delete local data:

docker compose down -v

This command can remove local database data.

Redis and queue

WrightTest uses Redis-backed background jobs for running browser checks and schedules.

Redis is required for:

  • manual check runs
  • scheduled runs
  • suite runs
  • background execution
  • runner queue processing

The example file uses:

  • REDIS_HOST
  • REDIS_PORT

If checks stay pending or do not start, check that Redis and the backend service are running.

docker compose ps
docker compose logs redis
docker compose logs backend

Browser runner

The backend service executes browser checks using Playwright.

It is responsible for:

  • opening browser contexts
  • executing check steps
  • collecting step results
  • taking screenshots
  • saving Playwright traces
  • marking runs as passed or failed

The example file uses:

  • NODE_ENV
  • WEBHOOK_SECRET
  • JWT_SECRET
  • JWT_EXPIRES_IN
  • SCREENSHOTS_DIR
  • TRACES_DIR

There is no separate worker container in the current Docker Compose setup. Manual runs, scheduled runs, queue processing, and scheduler logic are handled by the backend service.

If browser runs fail, check:

  • backend logs
  • browser availability
  • Playwright installation
  • access to the target URL
  • environment variables used by the check

noVNC recorder

WrightTest uses a noVNC-based browser recording flow to let users interact with a real browser from the web UI.

The recorder depends on:

  • a running browser container or virtual display
  • noVNC service
  • correct internal service URLs
  • available ports
  • browser access from the frontend

The example file uses:

  • VNC_PORT
  • NOVNC_PORT
  • VITE_NOVNC_URL
  • VITE_ENABLE_NOVNC

If the recorder does not open:

  • check that the noVNC service is running
  • check container logs
  • make sure required ports are not blocked
  • restart the stack
docker compose down
docker compose up --build

Screenshots and traces

Run results may include:

  • per-step screenshots
  • Playwright trace archives
  • failure summaries
  • raw errors

Make sure the services have write access to the storage location used for run artifacts.

The example file uses:

  • SCREENSHOTS_DIR
  • TRACES_DIR

If screenshots or traces are missing, check:

  • backend logs
  • storage path configuration
  • file permissions
  • whether the run failed before browser tracing started

App environment variables vs project environments

There are two different types of configuration in WrightTest.

App environment variables

These are configured in .env.

They control the application itself:

  • frontend URL
  • backend API URL
  • database connection
  • Redis connection
  • authentication secret
  • runner settings
  • noVNC settings

Project environments

These are created inside the WrightTest UI in the Environments tab.

They are used inside browser checks.

Example:

BASE_URL=https://playwright.dev

Then in a check:

Start URL: {{BASE_URL}}

Use app environment variables for infrastructure configuration.

Use project environments for check data, target URLs, usernames, passwords, and other reusable test values.

Browser support

WrightTest currently runs checks with Chromium.

Firefox and WebKit are not supported in the current version.

If your workflow requires Firefox or WebKit coverage, treat this as a current limitation and track roadmap updates.

Secrets

Use strong random values for authentication and signing secrets.

Do not commit .env files to Git.

Do not expose tokens, webhook URLs, bot tokens, or passwords in screenshots, traces, public logs, or support requests.

If a secret is leaked, rotate it immediately.

Restarting after configuration changes

After changing .env, restart the stack:

docker compose down
docker compose up --build

If you only need to restart without rebuilding:

docker compose restart

Next steps

After configuration, continue with:

Quick StartTroubleshooting