- Explain opt-in configuration, protected surfaces, migrations and cookie behavior. - Document operator CLI, MCP bearer use, cleanup, and supported local origins.
66 lines
3.4 KiB
Markdown
66 lines
3.4 KiB
Markdown
# liqa
|
|
|
|
A browser automation and QA service for web applications. It stores multi-step browser scenarios, runs them with [Playwright](https://playwright.dev/) in headless Chromium, and keeps their results, logs and artifacts. Scenarios are managed from a web UI, a REST API, or an **MCP (Model Context Protocol)** server that lets AI agents define, run and debug them.
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
No configuration is needed: every setting has a default. To override one, copy `.env.example` to `.env` and uncomment it.
|
|
|
|
Authentication is **disabled by default**. To enable operator-managed accounts, set `AUTH_ENABLED=true` and provide a private `AUTH_JWT_SECRET`; then rebuild/restart the service and provision an account with the CLI. See [operator authentication](docs/development.md#operator-account-commands) for setup and browser/API usage. Existing deployments remain unauthenticated until explicitly enabled.
|
|
|
|
Everything is served from one container at **http://localhost:13000**: the UI at `/`, the REST API at `/api/v1`, MCP at `/mcp`, Swagger at `/docs`. Data is kept in `./data/`.
|
|
|
|
To see it work, import and run the [self-test example](examples/self-test/): a scenario that tests liqa itself using an environment, a credential and snippets.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
To install liqa from the published image, without cloning this repo:
|
|
|
|
```bash
|
|
curl -fsSL https://git.hq.ars9.space/ars9/liqa/raw/branch/master/scripts/install.sh | bash
|
|
```
|
|
|
|
This asks for an install directory, a port and a version (latest by default), then writes a `compose.yaml` and a `data/` directory there. Start it with `docker compose up -d` in that directory.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
| Concept | Description |
|
|
|---|---|
|
|
| **Scenario** | An ordered list of steps (async Playwright JS) that run in sequence in one browser. Versioned: every content change creates a new version |
|
|
| **Run** | One execution of a scenario version in an environment, with per-step status and output, logs, and run files (downloads, failure screenshots, Playwright traces) |
|
|
| **Snippet** | Reusable, versioned code called from steps with `context.runSnippet("alias")` (or `"alias@N"` for a specific version) |
|
|
| **Environment** | A named set of key/value settings for a deployment target (URLs etc.), read with `context.getEnv(key)` |
|
|
| **Credential** | Secret data (e.g. a key file and password), assigned to scenarios under an alias and read with `context.getCredential(alias)` |
|
|
| **Session** | Saved browser state (cookies + localStorage), e.g. kept from a run with "save session" |
|
|
|
|
Scenarios, snippets, environments and credentials can be exported as YAML and imported back (one file may hold several of them).
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
- [docs/architecture.md](docs/architecture.md) - components, data model, client
|
|
- [docs/scenario.md](docs/scenario.md) - runs, the script `context` API, versioning, import/export, Playwright traces
|
|
- [docs/mcp.md](docs/mcp.md) - MCP tool reference
|
|
- [docs/development.md](docs/development.md) - setup, configuration, running, testing, linting, Docker
|
|
- [examples/](examples/) - ready-to-import example scenarios
|
|
- [CHANGELOG.md](CHANGELOG.md) - release notes
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE) © 2026 Andrii Arsenin
|
|
|
|
Third-party packages keep their own licenses. The Docker image includes all their notices, and the app serves them at `/licenses.txt` (linked as "Licenses" in the sidebar footer). See [docs/development.md](docs/development.md#licenses).
|