Troubleshooting

This page covers common issues you may encounter when installing, running, or using WrightTest.

Start with the section that matches your problem. If you are not sure where the issue is, check container status and logs first.

Check container status

In a Docker setup, start by checking running services:

docker compose ps

Then inspect logs:

docker compose logs

Common services may include:

• frontend
• backend
• postgres
• redis
• novnc

Service names depend on your docker-compose.yml.

The current Docker Compose setup does not run a separate worker container. Manual runs, scheduled runs, queue processing, and scheduler logic are handled by the backend service.

For a specific service, use the actual service name, for example:

docker compose logs backend
docker compose logs postgres
docker compose logs redis
docker compose logs novnc
docker compose logs frontend

Health checks

If the backend is reachable, you can check the HTTP health endpoints:

curl http://localhost:3000/health
curl http://localhost:3000/health/db

The application does not open

Symptoms:

• Browser cannot open the WrightTest URL
• The page shows a connection error
• The frontend container exits

What to check:

• Make sure containers are running:

docker compose ps

• Check frontend logs:

docker compose logs frontend

• Check that the frontend port is available
• Restart the stack:

docker compose down
docker compose up --build

The app opens, but data is missing

Symptoms:

• Dashboard opens but shows no projects or runs
• Requests fail in browser DevTools
• Pages show loading or empty states unexpectedly

What to check:

• Make sure the backend API is running
• Check that the frontend points to the correct API URL
• Check backend logs
• Check browser DevTools Network tab for failed API requests

docker compose logs backend

Browser checks stay pending

Symptoms:

• A check run is created but never starts
• Run status stays pending
• Dashboard and Runs page do not update

Common causes:

• Redis is not running
• Queue worker cannot connect to Redis
• Backend process cannot access the database or API

What to check:

docker compose ps
docker compose logs redis
docker compose logs backend

Restart the stack if needed:

docker compose down
docker compose up --build

Browser check fails immediately

Symptoms:

• Run status becomes failed very quickly
• No screenshots are generated
• Trace is unavailable
• Error mentions browser launch, executable path, or missing dependencies

Common causes:

• Playwright browser is not installed
• Browser container is not available
• Backend does not have required OS dependencies
• The target URL is not reachable from inside the container

What to check:

Install Playwright browsers if needed:

pnpm exec playwright install

If your runner uses Docker images with browsers preinstalled, rebuild containers:

docker compose up --build

Check backend logs:

docker compose logs backend

Recorder does not open

Symptoms:

• Clicking Start recording opens an empty or broken recorder view
• noVNC does not connect
• Browser window is not visible
• Recording session never starts

Common causes:

• noVNC service is not running
• Browser or virtual display service is not running
• Required ports are blocked or already in use
• Internal recorder URLs are misconfigured

What to check:

• Check noVNC service status:

docker compose ps

• Check noVNC logs:

docker compose logs novnc

• Check backend logs for recording session errors
• Restart the stack:

docker compose down
docker compose up --build

Environment variable is not resolved

Symptoms:

• Check uses {{BASE_URL}}, but the run opens an invalid URL
• Run fails because target URL is empty
• Schedule run behaves differently from manual run

What to check:

• Open the project Environments tab
• Make sure the environment exists
• Make sure BASE_URL is defined
• Make sure the check or schedule uses the correct environment
• Check variable spelling

Variables are case-sensitive.

Correct:

{{BASE_URL}}

Incorrect:

{{base_url}}

Check fails because an element is not found

Symptoms:

• Error mentions timeout
• Error mentions locator
• Failed step is Click element, Wait for element, or an assertion
• Screenshot shows the page, but the expected element is missing

What to check:

• Open the Run Result page
• Check the failed step
• Review the screenshot for the failed step
• Open the Playwright trace if available
• Confirm the locator is stable
• Add a wait step if the element appears asynchronously
• Prefer role-based or test-id locators where possible

If the page loads dynamic content, a check may need an explicit wait step before the assertion.

Trace is unavailable

Symptoms:

• Run Result shows Trace unavailable
• No trace viewer is shown
• Download trace is not available

Common causes:

• Browser context failed before tracing started
• Runner failed before the trace could be saved
• Storage path is not writable
• Trace file was deleted or not persisted

What to check:

• Check backend logs
• Check artifact storage permissions
• Verify that the run reached browser execution
• Re-run the check

docker compose logs backend

If screenshots exist but trace does not, the issue may be in trace finalization or artifact storage.

Screenshots are missing

Symptoms:

• Run result exists, but screenshots are not shown
• Step results exist without screenshot links

Common causes:

• Screenshot storage path is not writable
• Runner failed before screenshots were captured
• Artifact URL configuration is incorrect
• Files were removed from the artifact volume

What to check:

• Check backend logs
• Check backend API artifact routes
• Check storage permissions
• Re-run the check

Schedule does not run

Symptoms:

• Schedule is active, but no runs are created
• Next run time passes without execution
• Schedule history is empty

Common causes:

• Scheduler process is not running
• Redis queue is unavailable
• Cron expression is incorrect
• Timezone expectation is wrong
• Target check or suite was deleted

What to check:

• Open the Schedules tab
• Verify schedule status is Active
• Check cron expression and timezone
• Check backend logs
• Check Redis logs
• Try Run now

docker compose logs backend
docker compose logs redis

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.

Alert notification is not sent

Symptoms:

• Telegram or Slack alert is configured
• Run fails, but no notification arrives
• Test notification fails

What to check:

For Telegram:

• Bot token is correct
• Chat ID is correct
• Bot was added to the chat or channel
• Bot has permission to send messages

For Slack:

• Webhook URL is correct
• Webhook is still active
• Workspace did not revoke the webhook

Also check:

• notification rules
• alert channel status
• backend logs

docker compose logs backend

Alert is too noisy

Cause:

• Passed run notifications may be enabled

Recommendation:

• Failed runs: enabled
• Recovered runs: enabled
• Passed runs: disabled

This sends notifications when something breaks and when it recovers, without sending a message for every successful run.

Import from .spec.ts does not parse all steps

Symptoms:

• Some Playwright commands are missing after import
• Imported check has fewer steps than expected
• Custom helper functions are ignored

Explanation:

WrightTest can import common Playwright actions and assertions, but complex custom code may not map cleanly to visual steps.

What to do:

• Review imported steps manually
• Add missing steps in the editor
• Keep exported and imported specs simple when using the visual editor
• Use native Playwright code for complex scenarios that do not fit the visual step model

When to check logs

Check logs whenever:

• a run stays pending
• trace is unavailable
• screenshots are missing
• schedules do not fire
• alerts are not sent
• the recorder does not open
• the backend returns errors

Useful commands:

docker compose ps
docker compose logs
docker compose logs backend
docker compose logs postgres
docker compose logs redis
docker compose logs novnc
docker compose logs frontend

Still stuck?

When reporting an issue, include:

• WrightTest version
• git commit
• browser check name
• project name
• run ID
• error message
• screenshot of the Run Result page
• relevant container logs

Do not include secrets, webhook URLs, bot tokens, passwords, or .env files in public issue reports.