Files
liqa/README.md
T
ars9andClaude Opus 5.5 48c15bd282 feat(examples): add self-test example
- add examples/ with a ready-to-import self-test: environment, credential,
  snippets and a scenario that creates, runs and checks another scenario
  through the liqa REST API and UI, then cleans up
- add test/examples.spec.ts: imports every example and parses its code
- link the examples from README, docs/scenario.md and CLAUDE.md

Closes #6

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 15:38:22 +03:00

64 lines
3.0 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.
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).