Skip to main content
Chatwoot’s current browser E2E tests live in tests/playwright/. They have their own dependencies, configuration and package scripts, separate from the application root.
These instructions apply to the current development branch. For an older checkout, follow the testing configuration and README included in that version.

​
Start a local Chatwoot instance

Complete the Project Setup Guide or Docker Development Setup, then leave the application running at http://localhost:3000. You need an existing administrator account for the login and settings tests. Use a local development or test instance: E2E scenarios can create agents and inboxes.

​
Install the test dependencies

From the Chatwoot repository root:
The current configuration runs the Chromium project. On Linux, if Playwright reports missing browser system dependencies, follow its browser dependency instructions.

​
Configure the test account

Edit tests/playwright/.env and set:
Use the credentials of the administrator account in your local instance. Keep this file local; do not commit credentials. The suite reads these values through playwright.config.ts. If your local application uses a different port, update BASE_URL to match it.

​
Run the tests

Run commands from tests/playwright/, with Chatwoot still running in another terminal.

​
Run the suite

​
Use the test runner UI

​
Run one test file

​
List tests without running them

The current project launches a visible browser by default. For an environment without a desktop, set use.headless to true in playwright.config.ts.

​
Write and maintain tests

The test project uses TypeScript and page components under components/ui/. Add browser scenarios under tests/e2e/ui/ and reuse those components for login and navigation. For JavaScript unit tests, use pnpm test from the Chatwoot application root. For Ruby tests, use bundle exec rspec.