# Development ## Prerequisites - Node.js 24+ (required by `engines` in `package.json`; the Docker image uses Node.js 24) - Docker + Docker Compose The repository is a **npm workspace monorepo** with two packages: | Workspace | Directory | Description | |---|---|---| | `server` | `server/` | NestJS API + MCP server | | `client` | `client/` | React 19 + Vite admin UI | Install all dependencies from the repo root: ```bash npm install npx playwright install --only-shell chromium # first time only: headless Chromium for the server ``` No `.env` is needed: every setting below has a default. To override settings, copy `.env.example` to `.env` and uncomment the ones you need. Docker Compose loads `.env` when it exists. ### Environment variables (server) All settings are validated at startup by `server/src/config/app.config.ts`. | Variable | Default | Description | |---|---|---| | `NODE_ENV` | `development` | `production` in the Docker image. Shown in the startup log, and selects the default CORS origins | | `CORS_ORIGINS` | *(empty)* | Comma-separated origins allowed to call the API cross-origin. When empty: the Vite dev server (`http://localhost:5173`, `http://127.0.0.1:5173`) unless `NODE_ENV=production`, then the compose port (`http://localhost:13000`, `http://127.0.0.1:13000`) | | `PORT` | `3000` | HTTP port | | `DB_PATH` | `data/liqa.db` | SQLite database file | | `FILES_DIR` | `data/files` | Where scenario files and run artifacts are stored | | `FILE_RUN_EXPIRATION_DAYS` | `7` | How long run artifacts (downloads, failure dumps, traces) are kept | | `FILE_CLEANUP_CRON` | `0 3 * * *` | When expired files are deleted | | `SESSION_IDLE_TIMEOUT_MINUTES` | `30` | Idle timeout before open sessions are closed | | `SESSION_DELETE_CLOSED_DAYS` | `7` | Retention period for closed sessions | | `PLAYWRIGHT_TRACE_MODE` | `off` | Default Playwright trace mode for runs: `on`, `retain-on-failure` or `off` (see [scenario.md](scenario.md)) | | `CLIENT_DIR` | *(empty)* | Directory with the built client to serve at `/` (the Docker image sets it to `client`); empty means the server doesn't serve the UI | | `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | _(Playwright default)_ | Path to a Chromium binary to use instead of Playwright's own. Not set in Docker: the image ships Playwright's `chromium-headless-shell` (matching the Playwright version) under `PLAYWRIGHT_BROWSERS_PATH=/ms-playwright`. | --- ## Starting the application ### Server **Development** (watch mode, restarts on file changes): ```bash npm -w server run start:dev ``` **Production build, then start**: ```bash npm -w server run build npm -w server run start:prod ``` The server listens on port **3000** by default. ### Client **Development** (Vite dev server with HMR): ```bash npm -w client run dev ``` The Vite dev server runs on **http://localhost:5173**. It has no API proxy: the client calls `VITE_API_URL` (default `/api/v1` on its own origin), and the server allows CORS from `http://localhost:5173`. So point it at a running server: ```bash npm -w client run dev:compose-api # API of the compose container (localhost:13000) VITE_API_URL=http://localhost:3000/api/v1 npm -w client run dev # API of a locally started server ``` **Production build**: ```bash npm -w client run build ``` The built files are emitted to `client/dist/`. --- ## Database migrations The SQLite schema is managed by TypeORM migrations in `server/src/database/migrations/`; `synchronize` is off. - **Docker:** the container applies pending migrations before starting the server. - **Locally:** build, then apply them before starting the server (it refuses to start while migrations are pending): ```bash npm -w server run build npm -w server run migration:run # apply pending migrations to DB_PATH npm -w server run migration:show # list migrations and whether they're applied ``` The scripts run from `server/`, so `DB_PATH` (default `data/liqa.db`) is relative to it, and they read `server/.env` if present, like the server does. **Changing the schema** (adding or changing an entity): 1. Change the entity and build (`npm -w server run build`). 2. Make sure your local database is on the latest migration (`migration:run`). 3. Generate a migration from the difference between the entities and that database: ```bash npm -w server run migration:generate -- src/database/migrations/AddSomething ``` 4. Review the generated file, then add its class to `MIGRATIONS` in `src/database/migrations/index.ts` (they're listed explicitly, oldest first). 5. Run the tests: `test/migrations.spec.ts` checks that the migrations produce exactly the schema the entities describe, and fails if an entity change has no migration. The initial migration (`Initial…`) adopts databases created before migrations existed (by `synchronize`): if the tables already exist, it's only recorded as applied. ## Running tests ### Server (Jest) ```bash npm -w server run test ``` Run a single spec file: ```bash npm -w server run test -- --no-coverage test/scenario.controller.spec.ts ``` Watch mode: ```bash npm -w server run test:watch ``` Print the NestJS logs of the test app (they're silenced by default; `DEBUG=test`): ```bash npm -w server run test:debug ``` ### Client (Vitest + Storybook) Storybook interaction tests (runs all `*.stories.tsx` files): ```bash npm -w client run test:storybook ``` Launch Storybook dev server (with live preview): ```bash npm -w client run storybook ``` --- ## Formatting code Both workspaces use [Prettier](https://prettier.io/). **Server** — rewrites `src/**/*.ts` and `test/**/*.ts`: ```bash npm -w server run format ``` **Client** — rewrites `src/**/*.{ts,tsx}` and `.storybook/**/*.{ts,tsx}`: ```bash npm -w client run format ``` --- ## Linting Both workspaces use [ESLint](https://eslint.org/) with `typescript-eslint`. The client also includes `eslint-plugin-react-hooks` and `eslint-plugin-react-refresh`. **Server:** ```bash npm -w server run lint # report issues npm -w server run lint:fix # report and auto-fix ``` **Client:** ```bash npm -w client run lint # report issues npm -w client run lint:fix # report and auto-fix ``` Both workspaces target zero errors. Run lint before committing. --- ## Building the container The root `Dockerfile` builds a single image with the whole application: it builds the client and the server in separate stages, and the runtime image runs the server, which also serves the built client (`CLIENT_DIR`). The runtime image uses Playwright's headless-only Chromium build (`chromium-headless-shell`) with just the shared libraries it links against, plus DejaVu and Liberation fonts (Liberation is metric-compatible with Arial/Times, so pages lay out as they would with those fonts). All browser launches are headless, so the full desktop Chromium isn't installed. If a new Playwright version needs another library, `ldd` on the `chrome-headless-shell` binary in the image lists what's missing. ```bash docker compose build ``` To rebuild without the layer cache: ```bash docker compose build --no-cache ``` --- ## Running with Docker Compose Start (detached): ```bash docker compose up -d ``` Build and start in one step: ```bash docker compose up -d --build ``` Everything is served by the single `liqa` container at **http://localhost:13000**: the UI at `/`, the REST API at `/api/v1`, MCP at `/mcp`, Swagger at `/docs` and health at `/health`. Unknown paths outside those routes get the client's `index.html`, so client-side routes survive a page refresh. When switching from the old two-container setup (`server` + `client`), remove the old containers with `docker compose up -d --build --remove-orphans`. The SQLite database and stored files are persisted in `./data/`, which is volume-mounted into the container. Stop and remove containers: ```bash docker compose down ``` View logs: ```bash docker compose logs -f ``` --- ## Client overview The client (`client/`) is a React 19 + TypeScript SPA built with Vite. It provides a browser UI for managing scenarios, runs, snippets, credentials, environments and sessions, and for importing exported YAML. ### Tech stack | Library | Purpose | |---|---| | React 19 + TypeScript | UI framework | | Vite 6 | Dev server and bundler | | react-router-dom 7 (`BrowserRouter`) | Client-side routing | | @tanstack/react-query | Data fetching (cross-scenario runs list) | | i18next + react-i18next | Internationalisation | | lucide-react | Icon library | | @monaco-editor/react | Code editor for steps and snippets | | react-markdown + highlight.js | Markdown descriptions and code highlighting | | yaml | YAML export of entities | | moment | Relative timestamp formatting | | ESLint 10 + Prettier | Linting and formatting | | Storybook 10 + Vitest | Component development and testing | ### Directory layout ``` client/ src/ api/ API client (client.ts) and types (types.ts) components/ modals/ - run, export, export logs and delete confirmation modals hooks/ useTheme, usePageTitle, useRunDefaults, useImportFile i18n/ i18next bootstrap + locales/en.json lib/ highlight.js setup, API error toast events pages/ scenario/, run/, snippet/, credential/, environment/, session/, import/ ui/ Reusable component library (Badge, Button, Card, CodeEditor, Modal, Select, SidePanel, Table, Toast, ... - see ui/index.ts) .storybook/ stories/ *.stories.tsx for ui/ components ``` ### Routing `BrowserRouter` with plain paths. The root and unknown paths redirect to `/scenarios`. The server answers these paths with the client's `index.html` (see [architecture.md](architecture.md)), so they work on refresh. | Route | Page | |---|---| | `/scenarios` | Scenario list | | `/scenarios/:id` | Scenario details (steps, versions, credentials, used snippets, files) | | `/scenarios/:id/runs`, `/scenarios/:id/runs/:runId` | Runs of a scenario, run details | | `/runs` | Cross-scenario runs list | | `/snippets`, `/credentials`, `/environments`, `/sessions` | Entity lists (plus `/:id`, `/new`, `/:id/edit` where applicable) | | `/import` | Central import | ### Theming Light/dark theme is toggled by the `ThemeSwitcher` button in the sidebar footer. The selection is persisted to `localStorage` and applied as `data-theme` on `` before React mounts (anti-FOUC inline script in `index.html`). The sidebar footer also shows the app version read from the workspace root `package.json` and injected via Vite `define`.