- update client and server dependencies within their ranges, keeping all playwright packages aligned at 1.63 - fix code flagged by react-hooks 7.1: refs written during render and synchronous setState in effects - add stories for the ui components that had none, with interaction tests, and cover all DescriptionList layouts - drop the unused mdx stories pattern - run the storybook tests as part of the pre-commit checks - bump version to 1.20.1
57 lines
4.7 KiB
Markdown
57 lines
4.7 KiB
Markdown
# liqa
|
|
|
|
liqa is a browser automation and QA service for web applications. It stores **scenarios** (ordered Playwright steps), **snippets** (reusable code run via `context.runSnippet`), **environments**, **credentials** and **sessions**, and runs scenarios in headless Chromium. Scenarios and snippets are versioned; each run records the scenario version it executed.
|
|
|
|
It is an npm workspace with two packages:
|
|
|
|
- `server/` - NestJS API + scheduler + MCP server, SQLite via TypeORM; the schema is managed by migrations in `server/src/database/migrations/` (see "Database migrations" in `docs/development.md`). Any entity change needs a generated migration - `test/migrations.spec.ts` fails otherwise. REST API under `/api/v1`, Swagger UI at `/docs`, MCP at `/mcp`, health at `/health`.
|
|
- `client/` - React 19 + Vite SPA (i18n strings in `client/src/i18n/locales/en.json`).
|
|
|
|
## Docs
|
|
|
|
- [README.md](README.md) - overview
|
|
- [docs/architecture.md](docs/architecture.md) - services and modules
|
|
- [docs/development.md](docs/development.md) - local setup, running, testing, Docker
|
|
- [docs/scenario.md](docs/scenario.md) - scenario execution, script `context` API, versioning, export/import, Playwright traces
|
|
- [docs/mcp.md](docs/mcp.md) - MCP tool reference
|
|
- [CHANGELOG.md](CHANGELOG.md) - release notes per version
|
|
- [Dockerfile](Dockerfile) - single image: builds client and server, runtime serves both
|
|
- [.env.example](.env.example) - all configuration variables (validated in `server/src/config/app.config.ts`)
|
|
|
|
## Default deployment (docker compose)
|
|
|
|
`compose.yaml` at the repo root runs a single `liqa` container, built from the root `Dockerfile`, at http://localhost:13000. The server serves everything: the UI at `/` (the built client, via `CLIENT_DIR`), the REST API at `/api/v1`, MCP at `/mcp`, Swagger at `/docs`. It reads `.env` if present (optional - every setting has a default) and mounts `./data` (SQLite DB `data/liqa.db` + stored files).
|
|
|
|
Rebuild and restart: `docker compose up -d --build`. Check with `docker compose ps`, `curl localhost:13000/health` and `docker compose logs liqa`.
|
|
|
|
The live database is `data/liqa.db`. The container applies pending migrations before starting the server, so back it up before deploying a release with new migrations.
|
|
|
|
## Code quality
|
|
|
|
Before committing, run and pass all of these (and report the results):
|
|
|
|
```bash
|
|
# server
|
|
cd server && npm run lint && npx tsc --noEmit -p tsconfig.json && npm test && npm run build
|
|
# client
|
|
cd client && npm run lint && npm run build && npm run test:storybook
|
|
```
|
|
|
|
- Lint must stay clean in both packages (no errors, no warnings).
|
|
- `test:storybook` runs every story in `client/.storybook/stories/` in headless Chromium (needs `npx playwright install --only-shell chromium` once, and again after Playwright updates). Add or update a story when adding or changing a `client/src/ui/` component.
|
|
- Don't run prettier over whole existing files; several aren't prettier-clean and it produces unrelated diffs. Format only new files or the lines you changed.
|
|
- Server tests use an in-memory DB, a Playwright mock (`server/test/__mocks__/playwright.ts`), and a temporary files directory per test app (see `server/test/app.harness.ts`).
|
|
- Import Node.js built-in modules with the `node:` prefix (`node:fs`, `node:path`, `node:crypto`, ...).
|
|
|
|
## Committing a new version
|
|
|
|
When asked to commit:
|
|
|
|
1. **Ask which version to bump** - major, minor or patch - and propose a sensible default based on the changes: patch for fixes and small behavior/default tweaks, minor for new features, major for breaking changes (e.g. changed API or export/import formats that old clients or files can't use).
|
|
2. Run the code quality checks above.
|
|
3. Bump `version` in the root `package.json` and in both places at the top of `package-lock.json` (the root entry and `packages[""]`). `server/package.json` and `client/package.json` keep their own versions; don't bump them.
|
|
4. Add a `## <version> - <YYYY-MM-DD>` entry at the top of `CHANGELOG.md` ("Changes since <previous version>:", then `### Added` / `### Changed` / `### Fixed`). Mark breaking changes with **Breaking:**.
|
|
5. Update the docs affected by the change (`docs/*.md`, `README.md`, `.env.example`, MCP tool descriptions).
|
|
6. Build the commit message with the `/git-commit` skill if it is available, following its format and rules. Otherwise use a conventional commit message (`type(scope): subject`, then a bullet list body). Either way, put the version bump in the body as a bullet (e.g. `- bump version to <version>`), not in the subject line. This overrides the skill's rule of putting versions in the subject. Then make the commit with that message.
|
|
7. **After committing, ask the user whether to rebuild and restart the docker compose containers** (`docker compose up -d --build`); don't do it without confirmation.
|