- rewrite architecture, development, mcp and scenario docs to match the current code: single container, all mcp tools, runs, versioning, timeouts, settings, client routing and dev setup - rewrite README as a general overview without liquio-specific wording - remove the unused KEYS_DIR setting and ./keys compose mount - remove the unused result parameter from step code execution - complete .env.example with the file storage settings and fix the DB_PATH default
278 lines
8.4 KiB
Markdown
278 lines
8.4 KiB
Markdown
# 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
|
|
```
|
|
|
|
Copy `.env.example` to `.env` and fill in the required values before running.
|
|
|
|
### Environment variables (server)
|
|
|
|
All settings are validated at startup by `server/src/config/app.config.ts`.
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `NODE_ENV` | `development` | Shown in the startup log |
|
|
| `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/`.
|
|
|
|
---
|
|
|
|
## 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 `<html>` 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`.
|