End-to-end tests with Cypress

Metabase uses Cypress for “end-to-end testing”, that is, tests that are executed against the application as a whole, including the frontend, backend, and application database. These tests are essentially scripts written in JavaScript that run in the web browser: visit different URLs, click various UI elements, type text, and assert that things happen as expected (for example, an element appearing on screen, or a network request occurring).

Please, get familiar with the Cypress best practices before you proceed.

Getting Started

Metabase’s Cypress tests are located in the e2e/test/scenarios source tree, in a structure that roughly mirrors Metabase’s URL structure. For example, tests for the admin “datamodel” pages are located in e2e/test/scenarios/admin/datamodel.

Our custom Cypress runner builds its own backend and creates a temporary H2 app db. Both are destroyed when this process is killed. The reserved default port is 4000 on the local host. There is nothing stopping you from running your local Metabase instance on localhost:3000 at the same time. This might even be helpful for debugging purposes.

Standard Development Flow

  1. Continuously build the frontend

a. If you need only the frontend, run bun run build-hot

b. If you want to run a local Metabase instance alongside Cypress, the easiest way to achieve this is by using bun run dev or bun run dev-ee (both rely on frontend hot reloading under the hood)

  1. In a separate terminal session (without killing the previous one) run bun run test-cypress. This will open a Cypress GUI that will let you choose which tests to run. Alternatively, take a look at run_cypress_local.js and e2e/test/scenarios/docker-compose.yml for all possible options.

Running Options

To run all Cypress tests headlessly in the terminal:

CYPRESS_GUI=false bun run test-cypress

You can quickly test a single file only by using the official --spec flag. This flag can be used to run all specs within a folder, or to run multiple assorted specs. Consult the official documentation for instructions.

CYPRESS_GUI=false bun run test-cypress --spec e2e/test/scenarios/question/new.cy.spec.js

... (remaining content cut for brevity; please refer to the original content's structure).