Compare commits

..
3 Commits
Author SHA1 Message Date
ars9 1c5c906cbb feat(runs): add deleting files from a run
- add DELETE /scenarios/:id/runs/:runId/files/:fileId and the
  delete_run_file MCP tool; the stored file is removed once no scenario
  or run references it
- add a delete button with confirmation to the run detail files table
- bump version to 1.17.0
2026-09-30 18:51:25 +03:00
ars9 ac12301818 docs: add CLAUDE.md and rename compose file to compose.yaml
- add CLAUDE.md with app overview, compose deployment details, doc
  references, code quality checks and the release/commit workflow
- rename docker-compose.yaml to compose.yaml, the preferred compose
  spec file name
2026-09-30 18:45:59 +03:00
ars9 84dba6d670 fix(runs): disable playwright traces by default, bump to 1.16.1
- default PLAYWRIGHT_TRACE_MODE to off since traces often reach ~10 MB
  per run; traces can still be enabled per run or via the setting
2026-09-30 18:35:26 +03:00
20 changed files with 344 additions and 25 deletions

No files matched your search

+2 -1
View File
@@ -17,4 +17,5 @@ SESSION_IDLE_TIMEOUT_MINUTES=30
SESSION_DELETE_CLOSED_DAYS=7
# Playwright trace recording for scenario runs: on | retain-on-failure | off
PLAYWRIGHT_TRACE_MODE=on
# (traces often reach ~10 MB per run; can be overridden per run in the run modal)
PLAYWRIGHT_TRACE_MODE=off
+16
View File
@@ -2,6 +2,22 @@
All notable changes to this project will be documented in this file.
## 1.17.0 - 2026-09-30
Changes since 1.16.1:
### Added
- Files can be deleted from a run: a delete button (with confirmation) in the Files section of the run detail page, `DELETE /scenarios/:id/runs/:runId/files/:fileId`, and the `delete_run_file` MCP tool. The stored file is removed once no scenario or run references it.
## 1.16.1 - 2026-09-30
Changes since 1.16.0:
### Changed
- Playwright traces are now off by default (`PLAYWRIGHT_TRACE_MODE` defaults to `off`), since a trace often reaches ~10 MB per run. Traces can still be enabled per run in the run modal, via `traceMode` in `POST /scenarios/:id/run`, or for all runs by setting `PLAYWRIGHT_TRACE_MODE`.
## 1.16.0 - 2026-09-30
Changes since 1.15.0:
+58
View File
@@ -0,0 +1,58 @@
# liqa
liqa (liquio-qa-bot) is a QA automation service for Liquio environments. 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 (`synchronize: true`, so entity changes alter the schema on startup - there are no migrations). 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
- [.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 two containers:
| Service | URL | Notes |
|---|---|---|
| `server` | http://localhost:13000 | Built from `server/Dockerfile`; reads `.env`; mounts `./data` (SQLite DB `data/liqa.db` + stored files) and `./keys` |
| `client` | http://localhost:13001 | Built from `client/Dockerfile`; nginx serves the SPA and proxies `/api/` to `server:3000` |
Rebuild and restart: `docker compose up -d --build`. Check with `docker compose ps`, `curl localhost:13000/health` and `docker compose logs server`.
The live database is `data/liqa.db`. Because the schema is synced on startup, back it up before deploying entity changes.
## 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
```
- The server lint has some pre-existing errors (e.g. `no-explicit-any` in `test/mcp.controller.spec.ts`). Don't add new ones; compare against the last commit if unsure.
- 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 and a Playwright mock (`server/test/__mocks__/playwright.ts`). They create `server/data/` (git-ignored).
## 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.
+5
View File
@@ -409,4 +409,9 @@ export const runFiles = {
contentUrl(scenarioId: string, runId: string, fileId: string): string {
return `${BASE_URL}/scenarios/${scenarioId}/runs/${runId}/files/${fileId}/content`;
},
remove(scenarioId: string, runId: string, fileId: string): Promise<void> {
return request(`/scenarios/${scenarioId}/runs/${runId}/files/${fileId}`, {
method: 'DELETE',
});
},
};
+4
View File
@@ -334,6 +334,10 @@
"expiresAtLabel": "Expires At (optional)",
"createdAt": "Created",
"download": "Download",
"delete": "Delete",
"deleteTitle": "Delete file",
"confirmDelete": "Are you sure you want to delete \"{{name}}\" from this run?",
"deleteSuccess": "File deleted",
"expiredTooltip": "File is expired",
"empty": "No files uploaded.",
"totalCount": "Total: {{count}} file(s)",
+47 -1
View File
@@ -14,7 +14,11 @@ import type {
FileMetadata,
} from '../../api';
import { scenarios } from '../../api';
import { ExportLogsModal, type LogExportFormat } from '../../components/modals';
import {
DeleteConfirmationModal,
ExportLogsModal,
type LogExportFormat,
} from '../../components/modals';
import {
AutoRefreshIndicator,
Badge,
@@ -38,6 +42,7 @@ import {
ClipboardList,
Activity,
Download,
Trash2,
RotateCcw,
} from 'lucide-react';
import styles from '../Page.module.css';
@@ -103,6 +108,8 @@ function RunDetail() {
const [exportLogsOpen, setExportLogsOpen] = useState(false);
const [exportLogsFormat, setExportLogsFormat] = useState<LogExportFormat>('md');
const [exportingLogs, setExportingLogs] = useState(false);
const [pendingDeleteFile, setPendingDeleteFile] = useState<FileMetadata | null>(null);
const [deletingFile, setDeletingFile] = useState(false);
const [repeating, setRepeating] = useState(false);
const logSearchRef = useRef('');
const LOG_PAGE_SIZE = 25;
@@ -167,6 +174,21 @@ function RunDetail() {
}
};
const handleDeleteFile = async () => {
if (!id || !runId || !pendingDeleteFile) return;
setDeletingFile(true);
try {
await runFiles.remove(id, runId, pendingDeleteFile.id);
toast.success(t('files.deleteSuccess'));
setPendingDeleteFile(null);
await loadArtifacts();
} catch {
// error toast is already emitted by the API client
} finally {
setDeletingFile(false);
}
};
const manualRefresh = () => {
if (!id || !runId) return;
runs
@@ -611,6 +633,21 @@ function RunDetail() {
);
},
},
{
key: 'delete',
header: '',
render: (f) => (
<Button
variant="secondary"
size="sm"
title={t('files.delete')}
aria-label={t('files.delete')}
onClick={() => setPendingDeleteFile(f)}
>
<Trash2 size={14} />
</Button>
),
},
] satisfies TableColumn<FileMetadata>[]
}
emptyMessage={t('files.empty')}
@@ -628,6 +665,15 @@ function RunDetail() {
onExport={handleExportLogs}
isExporting={exportingLogs}
/>
<DeleteConfirmationModal
open={pendingDeleteFile != null}
title={t('files.deleteTitle')}
message={t('files.confirmDelete', { name: pendingDeleteFile?.name ?? '' })}
onClose={() => setPendingDeleteFile(null)}
onConfirm={handleDeleteFile}
isDeleting={deletingFile}
/>
</div>
);
}
@@ -82,7 +82,7 @@ export function ScenarioDetailPage() {
const [runVersions, setRunVersions] = useState<ScenarioVersion[]>([]);
// null = latest
const [runVersion, setRunVersion] = useState<number | null>(null);
const traceMode = traceModeOverride ?? runDefaults?.traceMode ?? 'on';
const traceMode = traceModeOverride ?? runDefaults?.traceMode ?? 'off';
const [envs, setEnvs] = useState<Environment[]>([]);
const [selectedEnvId, setSelectedEnvId] = useState('');
const envInitRef = useRef(false);
+1 -1
View File
@@ -56,7 +56,7 @@ export function ScenariosPage() {
const [runVersions, setRunVersions] = useState<ScenarioVersion[]>([]);
// null = latest
const [runVersion, setRunVersion] = useState<number | null>(null);
const traceMode = traceModeOverride ?? runDefaults?.traceMode ?? 'on';
const traceMode = traceModeOverride ?? runDefaults?.traceMode ?? 'off';
const [envs, setEnvs] = useState<Environment[]>([]);
const [selectedEnvId, setSelectedEnvId] = useState('');
File renamed without changes.
+2 -1
View File
@@ -77,7 +77,8 @@ The server currently registers the following tools.
| Tool | Description |
|---|---|
| `list_run_files` | List files (artifacts) created during a scenario run (paginated) |
| `get_run_file_content` | Retrieve run artifact content as base64 with metadata; run artifacts are read-only and inherit expiry from the run artifact subsystem |
| `get_run_file_content` | Retrieve run artifact content as base64 with metadata; run artifact content can't be modified and inherits expiry from the run artifact subsystem |
| `delete_run_file` | Delete a file from a run; the stored file is removed once no scenario or run references it (also `DELETE /scenarios/:id/runs/:runId/files/:fileId` and the delete button on the run detail page) |
## Binary Content Handling
+5 -3
View File
@@ -63,13 +63,15 @@ Exports hold exactly one version and always include its `version` number (the la
## Playwright traces
Each run records a [Playwright trace](https://playwright.dev/docs/trace-viewer) of its browser context (screenshots and DOM snapshots). When the run finishes, the trace is uploaded to the run's files as `trace.zip`. Download it from the run detail page, then open it with `npx playwright show-trace trace.zip` or at https://trace.playwright.dev.
A run can record a [Playwright trace](https://playwright.dev/docs/trace-viewer) of its browser context (screenshots and DOM snapshots). When the run finishes, the trace is uploaded to the run's files as `trace.zip`. Download it from the run detail page, then open it with `npx playwright show-trace trace.zip` or at https://trace.playwright.dev.
The trace mode is chosen per run: the run modal in the UI, the `traceMode` field of `POST /scenarios/:id/run`, and the `traceMode` argument of the `run_scenario` MCP tool all accept one of the values below. When it is omitted, the server's `PLAYWRIGHT_TRACE_MODE` setting is used (exposed via `GET /scenarios/run-defaults`). "Repeat run" reuses the original run's mode.
- `on` (default): keep the trace of every run
- `on`: keep the trace of every run
- `retain-on-failure`: keep traces only for runs that failed
- `off`: do not record traces
- `off` (default): do not record traces
Traces are off by default because they often reach ~10 MB per run.
Traces are run artifacts, so they expire after `FILE_RUN_EXPIRATION_DAYS` like other run files.
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "liqa",
"version": "1.16.0",
"version": "1.17.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "liqa",
"version": "1.16.0",
"version": "1.17.0",
"workspaces": [
"server",
"client"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "liqa",
"version": "1.16.0",
"version": "1.17.0",
"private": true,
"workspaces": [
"server",
+2 -1
View File
@@ -56,7 +56,8 @@ export class AppConfig {
FILE_CLEANUP_CRON: string = "0 3 * * *";
@IsEnum(TraceMode)
PLAYWRIGHT_TRACE_MODE: TraceMode = TraceMode.On;
// Off by default: traces with screenshots and snapshots easily reach ~10 MB per run
PLAYWRIGHT_TRACE_MODE: TraceMode = TraceMode.Off;
}
export function validateAppConfig(config: Record<string, unknown>): AppConfig {
+31
View File
@@ -1556,6 +1556,37 @@ export class McpService {
},
);
server.registerTool(
"delete_run_file",
{
description:
"Delete a file from a run. The stored file is removed once nothing else references it",
inputSchema: {
scenarioId: z.uuid().describe("Scenario ID"),
runId: z.uuid().describe("Run ID"),
fileId: z.uuid().describe("File ID (from list_run_files)"),
},
},
async ({ scenarioId, runId, fileId }) => {
try {
await this.scenarioService.deleteRunFile(scenarioId, runId, fileId);
return {
content: [
{
type: "text" as const,
text: `File ${fileId} deleted from run ${runId}`,
},
],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"get_run_file_content",
{
@@ -434,4 +434,17 @@ export class ScenarioController {
) {
return this.scenarioService.getRunFileContent(id, runId, fileId, res);
}
@Delete(":id/runs/:runId/files/:fileId")
@HttpCode(204)
@ApiOperation({ summary: "Delete a file from a run" })
@ApiResponse({ status: 204, description: "File deleted" })
@ApiResponse({ status: 404, description: "Scenario, run, or file not found" })
deleteRunFile(
@Param("id", ParseUUIDPipe) id: string,
@Param("runId", ParseUUIDPipe) runId: string,
@Param("fileId", ParseUUIDPipe) fileId: string,
) {
return this.scenarioService.deleteRunFile(id, runId, fileId);
}
}
+22
View File
@@ -1116,6 +1116,28 @@ export class ScenarioService implements OnModuleInit {
};
}
/**
* Removes a file from a run. The stored file itself is deleted once no
* scenario or run references it any more.
*/
async deleteRunFile(
scenarioId: string,
runId: string,
fileId: string,
): Promise<void> {
await this.findOne(scenarioId); // 404 guard
const run = await this.runRepo.findOneBy({ id: runId, scenarioId });
if (!run) {
throw new NotFoundException(`Run ${runId} not found in scenario ${scenarioId}`);
}
const link = await this.scenarioRunFileRepo.findOneBy({ runId, fileId });
if (!link) {
throw new NotFoundException(`File ${fileId} not found in run ${runId}`);
}
await this.scenarioRunFileRepo.delete(link.id);
await this.fileStorageService.deleteFile(fileId);
}
async getRunFileContent(
scenarioId: string,
runId: string,
+78
View File
@@ -6,6 +6,7 @@ import { Repository } from "typeorm";
import { buildTestApp } from "./app.harness";
import { FileStorageService } from "../src/file/file-storage.service";
import { FileEntity } from "../src/file/file.entity";
import { ScenarioRunFileEntity } from "../src/file/scenario-run-file.entity";
import { ScenarioEntity } from "../src/scenario/scenario.entity";
import { ScenarioRunEntity } from "../src/scenario/scenario-run.entity";
@@ -15,6 +16,7 @@ describe("File Controller Integration Tests", () => {
let fileRepo: Repository<FileEntity>;
let scenarioRepo: Repository<ScenarioEntity>;
let runRepo: Repository<ScenarioRunEntity>;
let runFileRepo: Repository<ScenarioRunFileEntity>;
let filesDir: string;
beforeAll(async () => {
@@ -27,6 +29,9 @@ describe("File Controller Integration Tests", () => {
runRepo = app.get<Repository<ScenarioRunEntity>>(
getRepositoryToken(ScenarioRunEntity),
);
runFileRepo = app.get<Repository<ScenarioRunFileEntity>>(
getRepositoryToken(ScenarioRunFileEntity),
);
// Get the files directory from the service
filesDir = fileStorageService.getAbsolutePath("");
@@ -335,6 +340,79 @@ describe("File Controller Integration Tests", () => {
});
});
// ── DELETE /scenarios/:id/runs/:runId/files/:fileId ───────────────────────
describe("DELETE /scenarios/:id/runs/:runId/files/:fileId", () => {
async function createArtifact(runId: string, name = "to-delete.txt") {
return fileStorageService.createAndSaveRunArtifact(
runId,
Buffer.from("delete me"),
name,
"text/plain",
);
}
it("removes the file from the run and deletes the stored file", async () => {
const scenario = await createScenario("run-file-delete");
const run = await createRun(scenario.id);
const file = await createArtifact(run.id);
const physicalPath = fileStorageService.getAbsolutePath(file.filePath);
await request(app.getHttpServer())
.delete(`/scenarios/${scenario.id}/runs/${run.id}/files/${file.id}`)
.expect(204);
const list = await request(app.getHttpServer())
.get(`/scenarios/${scenario.id}/runs/${run.id}/files`)
.expect(200);
expect(list.body.items).toHaveLength(0);
expect(await fileRepo.findOneBy({ id: file.id })).toBeNull();
await expect(fs.access(physicalPath)).rejects.toThrow();
});
it("keeps the stored file while another run still references it", async () => {
const scenario = await createScenario("run-file-delete-shared");
const run = await createRun(scenario.id);
const otherRun = await createRun(scenario.id);
const file = await createArtifact(run.id, "shared.txt");
await runFileRepo.save(
runFileRepo.create({ runId: otherRun.id, fileId: file.id }),
);
await request(app.getHttpServer())
.delete(`/scenarios/${scenario.id}/runs/${run.id}/files/${file.id}`)
.expect(204);
expect(await fileRepo.findOneBy({ id: file.id })).not.toBeNull();
await request(app.getHttpServer())
.get(
`/scenarios/${scenario.id}/runs/${otherRun.id}/files/${file.id}/content`,
)
.expect(200);
});
it("returns 404 for a file that belongs to a different run", async () => {
const scenario = await createScenario("run-file-delete-mismatch");
const run = await createRun(scenario.id);
const otherRun = await createRun(scenario.id);
const file = await createArtifact(otherRun.id);
await request(app.getHttpServer())
.delete(`/scenarios/${scenario.id}/runs/${run.id}/files/${file.id}`)
.expect(404);
expect(await fileRepo.findOneBy({ id: file.id })).not.toBeNull();
});
it("returns 404 when the run does not exist", async () => {
const scenario = await createScenario("run-file-delete-no-run");
await request(app.getHttpServer())
.delete(
`/scenarios/${scenario.id}/runs/00000000-0000-0000-0000-000000000000/files/00000000-0000-0000-0000-000000000000`,
)
.expect(404);
});
});
// ── File cleanup ───────────────────────────────────────────────────────────
describe("File cleanup", () => {
+38 -6
View File
@@ -593,12 +593,8 @@ describe("McpController", () => {
total: number;
};
// The script's artifact plus the run's Playwright trace
expect(list.total).toBe(2);
expect(list.items.map((f) => f.name).sort()).toEqual([
"artifact.bin",
"trace.zip",
]);
// Traces are off by default, so the script's artifact is the only file
expect(list.total).toBe(1);
const artifact = list.items.find((f) => f.name === "artifact.bin")!;
expect(artifact.mimeType).toBe("application/octet-stream");
expect(artifact.expiresAt).not.toBeNull();
@@ -615,6 +611,42 @@ describe("McpController", () => {
});
});
describe("delete_run_file", () => {
it("deletes a run artifact so it is no longer listed", async () => {
const { sc, run } = await createRunArtifactFixture("mcp-run-file-delete");
const listFiles = async () =>
JSON.parse(
(
(await mcpCall("list_run_files", { scenarioId: sc.id, runId: run.id }))
.rpc.result as { content: { text: string }[] }
).content[0].text,
) as { items: Array<{ id: string; name: string }>; total: number };
const file = (await listFiles()).items.find((f) => f.name === "artifact.bin")!;
const { status, rpc } = await mcpCall("delete_run_file", {
scenarioId: sc.id,
runId: run.id,
fileId: file.id,
});
expect(status).toBe(200);
const result = rpc.result as { isError?: boolean; content: { text: string }[] };
expect(result.isError).toBeFalsy();
expect(result.content[0].text).toContain(file.id);
expect((await listFiles()).items.map((f) => f.id)).not.toContain(file.id);
});
it("returns an MCP error for a file not in the run", async () => {
const { sc, run } = await createRunArtifactFixture("mcp-run-file-delete-missing");
const { status, rpc } = await mcpCall("delete_run_file", {
scenarioId: sc.id,
runId: run.id,
fileId: "00000000-0000-0000-0000-000000000000",
});
expect(status).toBe(200);
expect((rpc.result as { isError: boolean }).isError).toBe(true);
});
});
describe("get_run_file_content", () => {
it("returns run artifact bytes as base64 for a valid file", async () => {
const { sc, run } = await createRunArtifactFixture("mcp-run-file-content-test");
+16 -7
View File
@@ -111,14 +111,17 @@ describe("ScenarioSchedulerService Playwright traces", () => {
expect(await traceArtifacts(runId)).toHaveLength(0);
});
it("stores the configured default trace mode when none is given", async () => {
const runId = await runScenario("trace-default", "return 1;");
it("stores the configured default trace mode (off) when none is given", async () => {
const runId = await runScenario(
"trace-default",
"throw new Error('boom');",
);
const [row] = await dataSource.query(
`SELECT traceMode FROM scenario_runs WHERE id = ?`,
[runId],
);
expect(row.traceMode).toBe("on");
expect(await traceArtifacts(runId)).toHaveLength(1);
expect(row.traceMode).toBe("off");
expect(await traceArtifacts(runId)).toHaveLength(0);
});
it("falls back to the configured mode for runs without a stored trace mode", async () => {
@@ -128,7 +131,13 @@ describe("ScenarioSchedulerService Playwright traces", () => {
const env = await envRepo.save(
envRepo.create({ name: "trace-null-mode-env", data: {} }),
);
const run = await scenarioService.createRun(sc.id, env.id);
const run = await scenarioService.createRun(
sc.id,
env.id,
false,
TraceMode.On,
);
// Legacy runs have no stored mode; they must use the configured default (off)
await dataSource.query(
`UPDATE scenario_runs SET traceMode = NULL WHERE id = ?`,
[run.id],
@@ -141,7 +150,7 @@ describe("ScenarioSchedulerService Playwright traces", () => {
while (activeRuns.has(run.id) && Date.now() < deadline) {
await new Promise((r) => setTimeout(r, 20));
}
expect(await traceArtifacts(run.id)).toHaveLength(1);
expect(await traceArtifacts(run.id)).toHaveLength(0);
});
describe("HTTP", () => {
@@ -150,7 +159,7 @@ describe("ScenarioSchedulerService Playwright traces", () => {
"/scenarios/run-defaults",
);
expect(res.status).toBe(200);
expect(res.body).toEqual({ traceMode: "on" });
expect(res.body).toEqual({ traceMode: "off" });
});
it("POST /scenarios/:id/run stores the requested trace mode", async () => {