---
title: End-to-end testing with Cypress
description: Guide to running Cypress end-to-end tests for Chatwoot
sidebarTitle: Cypress Testing
---

# End-to-end testing with Cypress

Chatwoot uses [Cypress](https://www.cypress.io/) for end-to-end testing. Use the following steps to run the tests on your local machine.

## Prepare the Test Server

Choose any of the given methods to run your Chatwoot test server.

<Tabs>
<Tab title="Local Installation">

### Using Local Chatwoot Installation

<Note>
You have to install the necessary dependencies as described in [setup guide](/contributing/project-setup/setup-guide) for this method to work.
</Note>

Navigate to Chatwoot codebase in your local machine and execute the following steps:

#### Create a fresh test database

```bash
RAILS_ENV=test bin/rake db:drop
RAILS_ENV=test bin/rake db:create
RAILS_ENV=test bin/rake db:schema:load
```

#### Start Chatwoot in the test environment

```bash
RAILS_ENV=test foreman start -f Procfile.test
```

Load the URL in the browser and wait for it to start up:
```
http://localhost:5050/app/login
```

</Tab>
<Tab title="Docker Setup">

### Using Docker

Follow the [docker setup guide](/contributing/project-setup/docker-setup) until you build the images.

#### Change the Rails Environment

Open `docker-compose.yaml` and update all the `RAILS_ENV` values from `development` to `test`:

```yaml
# In docker-compose.yaml
environment:
  - RAILS_ENV=test  # Change from development to test
```

#### Update the Port

Under rails section in your `docker-compose.yaml` update the port value as given below:

```yaml
# In docker-compose.yaml
ports:
  - 5050:3000  # Change from 3000:3000 to 5050:3000
```

#### Reset the Database

```bash
docker-compose run --rm rails bundle exec rails db:reset
```

#### Start Chatwoot Docker in the test environment

```bash
docker-compose up
```

Load the URL in the browser and wait for it to start up:
```
http://localhost:5050/app/login
```

</Tab>
</Tabs>

## Run Cypress

Load `localhost:5050` on your browser and ensure that the Chatwoot server is running.

Navigate to your Chatwoot local directory and execute the following command to run the Cypress tests:

```bash
pnpm cypress open --project ./spec
```

This will open the Cypress Test Runner where you can:

1. **Choose a browser** for running tests
2. **Select test files** to run individual or all tests
3. **Watch tests run** in real-time with step-by-step execution
4. **Debug failed tests** with detailed error information


## Getting Help

If you encounter issues with Cypress testing:

- **Cypress Documentation**: [Official Cypress Docs](https://docs.cypress.io/)
- **Cypress Best Practices**: [Testing Guide](https://docs.cypress.io/guides/references/best-practices)
- **Common Errors**: See [Common Errors](/contributing/project-setup/common-errors)
- **Community Support**: [Discord](https://discord.com/invite/cJXdrwS)

## Useful Resources

- **Cypress API Reference**: [https://docs.cypress.io/api/table-of-contents](https://docs.cypress.io/api/table-of-contents)
- **Testing Library**: [Testing utilities for better element selection](https://testing-library.com/)
- **Cypress Examples**: [Real-world examples](https://github.com/cypress-io/cypress-example-recipes)

---

Your Cypress testing environment is now ready for comprehensive end-to-end testing! 🧪 