- 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
281 lines
10 KiB
YAML
281 lines
10 KiB
YAML
# liqa self-test example: a scenario that tests the liqa instance it runs on.
|
|
#
|
|
# Import this file (Import page in the UI, POST /api/v1/import with
|
|
# Content-Type: application/yaml, or the import_yaml MCP tool), then run the
|
|
# "liqa self-test" scenario. See README.md next to this file.
|
|
#
|
|
# Every item has a fixed id, so importing the file again updates the same
|
|
# resources instead of creating duplicates.
|
|
---
|
|
# Environment: where the liqa under test is reachable from the liqa server
|
|
kind: environment
|
|
id: 418eacb0-ab16-4ad6-ab50-c0274fdc49f1
|
|
name: liqa-self-test
|
|
description: >-
|
|
The liqa instance the self-test scenario runs against. Steps run inside the
|
|
liqa server (the Docker container), so the compose deployment published at
|
|
http://localhost:13000 is reached at its in-container port 3000.
|
|
data:
|
|
# REST API base (without /api/v1)
|
|
liqa_url: http://localhost:3000
|
|
# Web UI base; use http://localhost:5173 with the Vite dev server
|
|
ui_url: http://localhost:3000
|
|
# Name prefix of the temporary resources the self-test creates and deletes
|
|
temp_prefix: "[self-test] "
|
|
# Value the target scenario reads from its own (temporary) environment
|
|
greeting: Hello from the liqa self-test
|
|
---
|
|
# Credential: test data handed over to the temporary target scenario
|
|
kind: credential
|
|
id: b0c9ccab-6743-4ac1-9017-d99e0f5d7474
|
|
name: liqa-self-test-fixture
|
|
data: '{"username":"self-test-user","token":"not-a-real-secret-0123456789"}'
|
|
---
|
|
# Snippet: liqa-api
|
|
kind: snippet
|
|
id: f9d2612c-266c-411a-9483-5d860599f208
|
|
version: 1
|
|
alias: liqa-api
|
|
title: Call the liqa REST API
|
|
description: >-
|
|
`context.runSnippet("liqa-api", method, path, body?)` sends a request to
|
|
`liqa_url` + `/api/v1` + path and returns the parsed JSON response (`null`
|
|
for an empty body). Throws on a non-2xx status.
|
|
code: |
|
|
const [method, path, body] = args;
|
|
const url = context.getEnv("liqa_url") + "/api/v1" + path;
|
|
const response = await context.page.request.fetch(url, {
|
|
method,
|
|
data: body,
|
|
// POST /scenarios/:id/run/:runId/wait blocks until the run finishes
|
|
timeout: 120_000,
|
|
failOnStatusCode: false,
|
|
});
|
|
const text = await response.text();
|
|
if (!response.ok()) {
|
|
throw new Error(`${method} ${path} returned ${response.status()}: ${text}`);
|
|
}
|
|
return text ? JSON.parse(text) : null;
|
|
---
|
|
# Snippet: liqa-run-and-wait
|
|
kind: snippet
|
|
id: b36c1075-2700-421f-a2e7-ab1a80adb7e7
|
|
version: 1
|
|
alias: liqa-run-and-wait
|
|
title: Run a scenario and wait for it
|
|
description: >-
|
|
`context.runSnippet("liqa-run-and-wait", scenarioId, environmentId)` starts
|
|
a run of the scenario's latest version and returns the finished run (with
|
|
its step runs and logs). Uses the liqa-api snippet.
|
|
code: |
|
|
const [scenarioId, environmentId] = args;
|
|
const run = await context.runSnippet(
|
|
"liqa-api",
|
|
"POST",
|
|
`/scenarios/${scenarioId}/run`,
|
|
{ environmentId },
|
|
);
|
|
context.log(`Started run ${run.id}, waiting for it to finish`);
|
|
return context.runSnippet(
|
|
"liqa-api",
|
|
"POST",
|
|
`/scenarios/${scenarioId}/run/${run.id}/wait`,
|
|
);
|
|
---
|
|
# Snippet: self-test-cleanup
|
|
kind: snippet
|
|
id: f99e3b17-d28d-4a80-8ae4-f7e8252e0be5
|
|
version: 1
|
|
alias: self-test-cleanup
|
|
title: Delete temporary self-test resources
|
|
description: >-
|
|
Deletes every scenario, credential and environment whose name starts with
|
|
the `temp_prefix` environment value, and returns how many were deleted.
|
|
Uses the liqa-api snippet.
|
|
code: |
|
|
const prefix = context.getEnv("temp_prefix");
|
|
let deleted = 0;
|
|
// Scenarios first: they reference the credentials and environments
|
|
for (const path of ["/scenarios", "/credentials", "/environments"]) {
|
|
const page = await context.runSnippet("liqa-api", "GET", `${path}?limit=1000`);
|
|
for (const item of page.data.filter((i) => i.name.startsWith(prefix))) {
|
|
await context.runSnippet("liqa-api", "DELETE", `${path}/${item.id}`);
|
|
context.log(`Deleted ${path.slice(1, -1)} "${item.name}"`);
|
|
deleted += 1;
|
|
}
|
|
}
|
|
return deleted;
|
|
---
|
|
# Scenario: liqa self-test
|
|
kind: scenario
|
|
id: 571b2894-dacc-4428-b459-4e3fefac5908
|
|
version: 1
|
|
name: liqa self-test
|
|
description: |
|
|
Tests the liqa instance it runs on, through its REST API and web UI:
|
|
|
|
1. checks that the instance is up and removes leftovers of earlier runs
|
|
2. creates a temporary environment, credential and two-step target scenario
|
|
3. runs the target scenario, waits for it and checks its step outputs and logs
|
|
4. opens the finished run in the web UI
|
|
5. deletes the temporary resources
|
|
|
|
Uses the `liqa-api`, `liqa-run-and-wait` and `self-test-cleanup` snippets and
|
|
the `fixture` credential. See `examples/self-test/README.md`.
|
|
environmentId: 418eacb0-ab16-4ad6-ab50-c0274fdc49f1
|
|
timeoutSeconds: 300
|
|
credentials:
|
|
- credentialId: b0c9ccab-6743-4ac1-9017-d99e0f5d7474
|
|
alias: fixture
|
|
steps:
|
|
- title: Check the instance is up
|
|
execCode: |
|
|
const response = await context.page.request.get(
|
|
context.getEnv("liqa_url") + "/health",
|
|
);
|
|
const health = await response.json();
|
|
context.assert(() => response.ok(), "Health endpoint responds", {
|
|
status: response.status(),
|
|
});
|
|
context.assert(() => health.status === "ok", "Health status is ok", health);
|
|
|
|
// A failed earlier run may have left its temporary resources behind
|
|
const deleted = await context.runSnippet("self-test-cleanup");
|
|
if (deleted > 0) {
|
|
context.warn(`Deleted ${deleted} leftover resource(s) of an earlier run`);
|
|
}
|
|
return health;
|
|
- title: Create the target scenario
|
|
execCode: |
|
|
const prefix = context.getEnv("temp_prefix");
|
|
const api = (method, path, body) =>
|
|
context.runSnippet("liqa-api", method, path, body);
|
|
|
|
const environment = await api("POST", "/environments", {
|
|
name: `${prefix}environment`,
|
|
data: { greeting: context.getEnv("greeting") },
|
|
});
|
|
// Hand the fixture credential over to the target scenario
|
|
const fixture = context.getCredential("fixture");
|
|
const credential = await api("POST", "/credentials", {
|
|
name: `${prefix}credential`,
|
|
data: JSON.stringify(fixture),
|
|
});
|
|
const scenario = await api("POST", "/scenarios", {
|
|
name: `${prefix}target scenario`,
|
|
description: "Temporary scenario created by the liqa self-test",
|
|
environmentId: environment.id,
|
|
timeoutSeconds: 60,
|
|
});
|
|
await api("POST", `/scenarios/${scenario.id}/credentials`, {
|
|
credentialId: credential.id,
|
|
alias: "secret",
|
|
});
|
|
|
|
await api("POST", `/scenarios/${scenario.id}/steps`, {
|
|
title: "Read the environment and credential",
|
|
execCode: `
|
|
const secret = context.getCredential("secret");
|
|
context.assert(() => typeof secret.token === "string", "Credential has a token");
|
|
// Return the token length, not the token: step outputs are not secret
|
|
return { greeting: context.getEnv("greeting"), tokenLength: secret.token.length };
|
|
`,
|
|
});
|
|
await api("POST", `/scenarios/${scenario.id}/steps`, {
|
|
title: "Render the greeting",
|
|
execCode: `
|
|
const { greeting } = await context.getStepOutput(-1);
|
|
await context.page.setContent("<h1>" + greeting + "</h1>");
|
|
await expect(context.page.locator("h1")).toHaveText(greeting);
|
|
return { heading: await context.page.locator("h1").textContent() };
|
|
`,
|
|
});
|
|
|
|
const created = await api("GET", `/scenarios/${scenario.id}`);
|
|
context.assert(
|
|
() => created.steps.length === 2,
|
|
"Target scenario has 2 steps",
|
|
{ steps: created.steps.length },
|
|
);
|
|
context.log(`Created target scenario ${scenario.id}`);
|
|
return {
|
|
scenarioId: scenario.id,
|
|
scenarioName: scenario.name,
|
|
environmentId: environment.id,
|
|
credentialId: credential.id,
|
|
};
|
|
- title: Run the target scenario
|
|
timeoutSeconds: 150
|
|
execCode: |
|
|
const { scenarioId, environmentId } = await context.getStepOutput(-1);
|
|
const run = await context.runSnippet(
|
|
"liqa-run-and-wait",
|
|
scenarioId,
|
|
environmentId,
|
|
);
|
|
context.assert(() => run.status === "pass", "Target run passed", {
|
|
status: run.status,
|
|
errors: run.logs.filter((l) => l.level === "error").map((l) => l.message),
|
|
});
|
|
context.assert(
|
|
() => run.stepRuns.every((s) => s.status === "pass"),
|
|
"All target steps passed",
|
|
run.stepRuns.map((s) => ({ order: s.order, status: s.status })),
|
|
);
|
|
|
|
const [read, render] = run.stepRuns.map((s) => JSON.parse(s.output));
|
|
const greeting = context.getEnv("greeting");
|
|
context.assert(
|
|
() => read.greeting === greeting,
|
|
"Target read the greeting from its environment",
|
|
read,
|
|
);
|
|
context.assert(
|
|
() => read.tokenLength === context.getCredential("fixture").token.length,
|
|
"Target read the token from its credential",
|
|
);
|
|
context.assert(
|
|
() => render.heading === greeting,
|
|
"Target rendered the greeting",
|
|
render,
|
|
);
|
|
context.assert(
|
|
() =>
|
|
run.logs.some(
|
|
(l) =>
|
|
l.context === "assertion:pass" &&
|
|
l.message === "Credential has a token",
|
|
),
|
|
"Target logged its passed assertion",
|
|
);
|
|
return { runId: run.id };
|
|
- title: Check the run in the UI
|
|
execCode: |
|
|
const { scenarioId, scenarioName } = await context.getStepOutput(2);
|
|
const { runId } = await context.getStepOutput(3);
|
|
const page = context.page;
|
|
await page.goto(
|
|
`${context.getEnv("ui_url")}/scenarios/${scenarioId}/runs/${runId}`,
|
|
);
|
|
await expect(page.getByText(scenarioName).first()).toBeVisible();
|
|
await expect(page.getByText("Credential has a token").first()).toBeVisible();
|
|
context.log(`Run page checked: ${page.url()}`);
|
|
return { url: page.url() };
|
|
- title: Clean up
|
|
execCode: |
|
|
const { scenarioId } = await context.getStepOutput(2);
|
|
const deleted = await context.runSnippet("self-test-cleanup");
|
|
context.assert(() => deleted === 3, "Deleted the 3 temporary resources", {
|
|
deleted,
|
|
});
|
|
|
|
const response = await context.page.request.get(
|
|
`${context.getEnv("liqa_url")}/api/v1/scenarios/${scenarioId}`,
|
|
);
|
|
context.assert(
|
|
() => response.status() === 404,
|
|
"Target scenario is gone",
|
|
{ status: response.status() },
|
|
);
|
|
return { deleted };
|