Testing Guide
=============


This page covers the main automated test entrypoints used during development, with extra focus on the local Playwright end-to-end workflow.

Backend Tests
-------------


Run the backend test suite from the repository root with:

.. code-block:: bash

   cd src/backend
   pytest tests/


Frontend Unit Tests
-------------------


Run the frontend unit tests with:

.. code-block:: bash

   npm --prefix src/frontend/app run test


End-to-End Tests
----------------


The Playwright suite starts the frontend in Vite development mode and drives a real Chromium browser against the backend development stack.

Before the first local run, install the browser once:

.. code-block:: bash

   npm --prefix src/frontend/app exec playwright install chromium


Run the full local smoke flow with:

.. code-block:: bash

   npm --prefix src/frontend/app run test:e2e:local


``test:e2e:local`` is the full fresh-stack entrypoint used for local smoke runs. It prepares the Docker-based backend services and then executes the Playwright suite. This mode is headless by default.

Watching the Browser Live
~~~~~~~~~~~~~~~~~~~~~~~~~


If you want to see what the tests are doing visually, use the fresh-stack headed entrypoint:

.. code-block:: bash

   npm --prefix src/frontend/app run test:e2e:local:headed


This opens Chromium, resets the e2e stack first, and shows the clicks, page transitions, uploads, and other interactions while the suite runs.

If you already started a clean e2e stack yourself and only want to run the browser suite, you can still use:

.. code-block:: bash

   npm --prefix src/frontend/app run test:e2e:headed


Use that browser-only command only against a freshly reset e2e database. The suite starts by creating the initial admin account, so reusing an existing dev database will make the first test fail.

Debug Mode
~~~~~~~~~~


For an interactive debugging session, run:

.. code-block:: bash

   npm --prefix src/frontend/app run test:e2e -- --debug


This opens the Playwright inspector and lets you step through actions interactively.

Notes
~~~~~


- ``test:e2e`` and ``test:e2e:headed`` assume the backend development services are already running.
- ``test:e2e:local`` and ``test:e2e:local:headed`` are the safest local entrypoints because they reset the Docker-based e2e stack for you.
- If you run only the browser suite, MailHog must also be reachable because the e2e tests assert email-delivery flows.
- When you start the e2e stack with ``docker-compose.e2e.yml``, the MailHog UI is exposed on ``http://127.0.0.1:18025`` by default.