Compare commits

..
4 Commits
Author SHA1 Message Date
ars9 73cfe99cb7 1.2.0 2026-04-08 20:14:10 +03:00
ars9 9e79cad237 feat(session): persistent browser context pool with lifecycle management
- SessionContextService: in-memory Map of live Playwright handles, reused
  per sessionName across exec_code/open_url calls; closed on module destroy
- SessionSchedulerService: @Interval closes idle sessions and deletes old
  closed ones using SESSION_IDLE_TIMEOUT_MINUTES / SESSION_DELETE_CLOSED_DAYS
- SessionService: onApplicationBootstrap closes all open sessions on restart;
  upsert marks status=open and sets lastUsedAt; adds markOpen/markClosed/
  touchLastUsed/findExpiredOpen/findOldClosed/findById helpers
- SessionEntity: status (open|closed) and lastUsedAt columns added
- AuthService: keeps browser alive after login, registers context in pool
- BrowserService: named sessions reuse persistent context; anonymous remain ephemeral
- AppConfig: all config fields declared with typed defaults; validate wired
  into ConfigModule so mis-configuration fails fast at startup
- ConfigService<AppConfig, true> used everywhere — no more untyped get() calls
2026-04-08 20:14:05 +03:00
ars9 b2edac062f 1.1.1 2026-04-08 19:02:53 +03:00
ars9 71bcc8faec feat(scenario): step output, getStepOutput helper, export/import MCP tools, doc restructure
- add output column to ScenarioRunStepEntity; exec step return value is JSON-serialised and stored
- expose helpers.getStepOutput(order) in exec code; negative order is relative to current step
- add get_scenario_run, wait_for_scenario_run, export_scenario, import_scenario MCP tools
- move Architecture, Key descriptors, MCP tools, Scenario, Development docs to docs/
- delete CONTRIBUTING.md (replaced by docs/development.md)
2026-04-08 19:02:36 +03:00
32 changed files with 1091 additions and 310 deletions

No files matched your search

+10 -1
View File
@@ -5,4 +5,13 @@ PORT=3000
KEYS_DIR=keys
# SQLite database path
DB_PATH=data/sessions.db
DB_PATH=data/sessions.db
# Playwright executable (set in Docker; leave empty to use system default)
# PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
# Session lifecycle
# Close open sessions that have been idle for longer than this many minutes
SESSION_IDLE_TIMEOUT_MINUTES=30
# Delete closed sessions whose updatedAt is older than this many days
SESSION_DELETE_CLOSED_DAYS=7
+6 -189
View File
@@ -19,211 +19,28 @@ The bot manages four core concepts:
## Architecture
```
MCP client (AI agent / VS Code Copilot)
│ HTTP (Streamable MCP)
▼
┌──────────────────────────────────┐
│ NestJS app (src/) │
│ │
│ McpService ← registers │
│ AuthService all tools │
│ BrowserService │
│ ScenarioService │
│ ScenarioSchedulerService │
│ └─ @Interval(1s) tick loop │
└──────────┬───────────────────────┘
│ better-sqlite3 (TypeORM)
▼
data/sessions.db
```
- **McpService** — registers every MCP tool and delegates to domain services.
- **AuthService** — logs in via Playwright using a key descriptor, saves the resulting session.
- **ScenarioSchedulerService** — polls for pending step runs every second and executes them. All steps belonging to the same run share **one browser instance** (see [Scenario execution](#scenario-execution)).
- **CodeExecutorService** — compiles and runs user-supplied Playwright JS inside a sandboxed `async` function with `page`, `context`, and `helpers` in scope.
---
## Environment variables
| Variable | Default | Description |
|---|---|---|
| `PORT` | `3000` | HTTP port |
| `KEYS_DIR` | `keys` | Directory containing `*.json` key descriptors |
| `DB_PATH` | `data/sessions.db` | SQLite database file |
| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | _(Playwright default)_ | Path to Chromium binary. Set automatically in Docker (`/usr/bin/chromium`). |
Copy `.env.example` to `.env` and adjust.
---
## Running locally
```bash
npm install
npx playwright install chromium # first time only
npm run start:dev
```
The MCP endpoint is available at `http://localhost:3000/mcp`.
With Docker:
```bash
docker build -t liquio-qa-bot .
docker run -p 3000:3000 -v $(pwd)/keys:/app/keys -v $(pwd)/data:/app/data liquio-qa-bot
```
See [docs/architecture.md](docs/architecture.md).
---
## Key descriptors
Each file in `KEYS_DIR` is named `<keyId>.json` and takes one of two forms:
**File key (EDS):**
```json
{
"keyFile": "path/to/key.dat",
"password": "secret"
}
```
`keyFile` is resolved relative to `KEYS_DIR`.
**Login + password:**
```json
{
"login": "user@example.com",
"password": "secret"
}
```
See [docs/key-descriptors.md](docs/key-descriptors.md).
---
## MCP tools
### Auth / session
| Tool | Description |
|---|---|
| `list_keys` | List available key IDs from `KEYS_DIR` |
| `login` | Log in with a key against an environment; stores resulting session |
| `list_sessions` | Paginated list of saved sessions |
| `delete_session` | Delete a session by ID |
### Environments
| Tool | Description |
|---|---|
| `list_environments` | Paginated list of environments |
| `get_environment` | Get one environment by ID |
| `create_environment` | Create an environment (`name` + `urls` map) |
| `update_environment` | Update name / urls |
| `delete_environment` | Delete by ID |
`urls` is a free-form map. Recognised keys: `id_url` (auth server), `cabinet_url` (cabinet redirect target), `admin_url`.
### Browser (ad-hoc, stateless)
| Tool | Description |
|---|---|
| `open_url` | Navigate to a URL and return page content / reader-mode text |
| `exec_code` | Run Playwright JS in a session's browser context |
### Scenarios
| Tool | Description |
|---|---|
| `list_scenarios` | Paginated list |
| `get_scenario` | Fetch scenario with all steps |
| `create_scenario` | Create a new scenario by name |
| `update_scenario` | Rename |
| `delete_scenario` | Delete (cascades to steps and runs) |
| `create_scenario_step` | Add a step |
| `get_scenario_step` | Fetch one step |
| `update_scenario_step` | Update step fields |
| `delete_scenario_step` | Remove a step |
| `list_scenario_runs` | Paginated run history (with optional status filter) |
| `run_scenario` | Trigger an immediate run |
See [docs/mcp.md](docs/mcp.md).
---
## Scenario execution
When a scenario is run, the scheduler creates a `ScenarioRun` with one `ScenarioRunStep` per step. Steps are executed **in order** (by `step.order`), one per scheduler tick.
**All steps in the same run share a single Playwright browser instance.** The browser is created on the first `exec` or `sign` step (using session cookies + localStorage), reused for every subsequent step, and closed when the run finishes (pass or fail).
### Step types
#### `login`
Authenticates in a **separate, ephemeral browser** and saves the resulting session to the database. Subsequent exec/sign steps load that session into the shared browser.
`execCode` must be a JSON object:
```json
{ "keyId": "3137411915", "environmentName": "liquio-diia-stg" }
```
#### `exec`
Runs arbitrary Playwright JS on the **shared page**. The page carries over state from the previous step (URL, form inputs, cookies, etc.).
`execCode` is executed as the body of an `async` function with these variables in scope:
- `page` — current Playwright `Page`
- `context` — current Playwright `BrowserContext`
- `helpers.dumpDom(selector?)` — returns a simplified DOM string
```js
// example execCode
await page.goto('https://cabinet.example.com/tasks/create/987825');
await page.locator('input[name="institution"]').fill('caltech');
await page.locator('button:has-text("Далі")').click();
await page.waitForLoadState('networkidle');
return page.url();
```
#### `sign`
Performs EDS signing on the **current shared page** using a key from `KEYS_DIR`. The step clicks the sign widget, selects the file key method, uploads the key file, enters the password, and submits — all without requiring the step author to handle key material in their code.
`execCode` must be a JSON object:
```json
{ "keyId": "3137411915" }
```
### Validation code
Any step type optionally accepts `validateCode` — Playwright JS that runs on the shared page **after** the main action and must return a result evaluated as:
```js
return { success: true, description: 'Application created' };
// or
return { success: false, description: 'Expected success banner not found' };
// or simply
return someBoolean;
```
If `success` is false the step (and the whole run) fails with the provided `description`.
### Run statuses
`pending` → `in_progress` → `pass` | `fail`
Individual step runs also expose `waiting` (not yet reached) and `cancelled` (run failed before this step).
See [docs/scenario.md](docs/scenario.md).
---
## Adding a new scenario (example workflow)
## Development
```
1. create_environment (if not already present)
2. create_scenario → get scenarioId
3. create_scenario_step type=login, order=0
4. create_scenario_step type=exec, order=1 (navigate + fill form)
5. create_scenario_step type=sign, order=2
6. create_scenario_step type=exec, order=3 (validateCode checks success banner)
7. run_scenario
8. list_scenario_runs (poll until status != in_progress)
```
See [docs/development.md](docs/development.md) for setup, running, testing, linting, and Docker instructions.
+34
View File
@@ -0,0 +1,34 @@
# Architecture
```
MCP client (AI agent / VS Code Copilot)
│ HTTP /mcp (Streamable MCP)
▼
┌──────────────────────────────────────┐
│ NestJS app (src/) │
│ │
│ McpService ← all MCP tools │
│ │
│ AuthService login + sessions │
│ SessionService session CRUD │
│ EnvironmentService environment CRUD │
│ BrowserService ad-hoc browsing │
│ CodeExecutorService sandboxed JS │
│ │
│ ScenarioService scenario CRUD │
│ ScenarioSchedulerService │
│ └─ @Interval(1 s) tick loop │
└──────────────────┬───────────────────┘
│ better-sqlite3 (TypeORM)
▼
data/sessions.db
```
- **McpService** — registers every MCP tool and delegates to domain services.
- **AuthService** — drives a Playwright browser to log in via a key descriptor; saves cookies + localStorage as a `Session`.
- **SessionService** — stores and retrieves saved browser sessions.
- **EnvironmentService** — stores named environments (URL maps) used by auth and scenarios.
- **BrowserService** — ad-hoc, stateless `open_url` / `exec_code` operations outside the scenario scheduler.
- **CodeExecutorService** — compiles and runs user-supplied Playwright JS inside a sandboxed `async` function with `page`, `context`, and `helpers` in scope.
- **ScenarioService** — CRUD for scenarios, steps, runs, and run logs; import/export.
- **ScenarioSchedulerService** — polls for pending step runs every second and executes them. All steps in the same run share **one browser instance** (see [scenario.md](scenario.md)).
+11 -1
View File
@@ -1,4 +1,4 @@
# Contributing
# Development
## Prerequisites
@@ -9,10 +9,20 @@ Install dependencies:
```bash
npm install
npx playwright install chromium # first time only
```
Copy `.env.example` to `.env` and fill in the required values before running.
### Environment variables
| Variable | Default | Description |
|---|---|---|
| `PORT` | `3000` | HTTP port |
| `KEYS_DIR` | `keys` | Directory containing `*.json` key descriptors |
| `DB_PATH` | `data/sessions.db` | SQLite database file |
| `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | _(Playwright default)_ | Path to Chromium binary. Set automatically in Docker (`/usr/bin/chromium`). |
---
## Starting the application
+20
View File
@@ -0,0 +1,20 @@
# Key descriptors
Each file in `KEYS_DIR` is named `<keyId>.json` and takes one of two forms:
**File key (EDS):**
```json
{
"keyFile": "path/to/key.dat",
"password": "secret"
}
```
`keyFile` is resolved relative to `KEYS_DIR`.
**Login + password:**
```json
{
"login": "user@example.com",
"password": "secret"
}
```
+49
View File
@@ -0,0 +1,49 @@
# MCP tools
## Auth / session
| Tool | Description |
|---|---|
| `list_keys` | List available key IDs from `KEYS_DIR` |
| `login` | Log in with a key against an environment; stores resulting session |
| `list_sessions` | Paginated list of saved sessions |
| `delete_session` | Delete a session by ID |
## Environments
| Tool | Description |
|---|---|
| `list_environments` | Paginated list of environments |
| `get_environment` | Get one environment by ID |
| `create_environment` | Create an environment (`name` + `urls` map) |
| `update_environment` | Update name / urls |
| `delete_environment` | Delete by ID |
`urls` is a free-form map. Recognised keys: `id_url` (auth server), `cabinet_url` (cabinet redirect target), `admin_url`.
## Browser (ad-hoc, stateless)
| Tool | Description |
|---|---|
| `open_url` | Navigate to a URL and return page content / reader-mode text |
| `exec_code` | Run Playwright JS in a session's browser context |
## Scenarios
| Tool | Description |
|---|---|
| `list_scenarios` | Paginated list |
| `get_scenario` | Fetch scenario with all steps |
| `create_scenario` | Create a new scenario by name |
| `update_scenario` | Rename |
| `delete_scenario` | Delete (cascades to steps and runs) |
| `create_scenario_step` | Add a step |
| `get_scenario_step` | Fetch one step |
| `update_scenario_step` | Update step fields |
| `delete_scenario_step` | Remove a step |
| `list_scenario_runs` | Paginated run history (with optional status filter) |
| `run_scenario` | Trigger an immediate run |
| `get_scenario_run` | Get a run with all step runs and their outputs |
| `wait_for_scenario_run` | Block until run reaches `pass`/`fail`, return full run |
| `export_scenario` | Export scenario as a portable JSON payload |
| `import_scenario` | Import a scenario from an export payload |
+80
View File
@@ -0,0 +1,80 @@
# Scenario execution
When a scenario is run, the scheduler creates a `ScenarioRun` with one `ScenarioRunStep` per step. Steps are executed **in order** (by `step.order`), one per scheduler tick.
**All steps in the same run share a single Playwright browser instance.** The browser is created on the first `exec` or `sign` step (using session cookies + localStorage), reused for every subsequent step, and closed when the run finishes (pass or fail).
## Step types
### `login`
Authenticates in a **separate, ephemeral browser** and saves the resulting session to the database. Subsequent exec/sign steps load that session into the shared browser.
`execCode` must be a JSON object:
```json
{ "keyId": "3137411915", "environmentName": "liquio-diia-stg" }
```
### `exec`
Runs arbitrary Playwright JS on the **shared page**. The page carries over state from the previous step (URL, form inputs, cookies, etc.).
`execCode` is executed as the body of an `async` function with these variables in scope:
- `page` — current Playwright `Page`
- `context` — current Playwright `BrowserContext`
- `helpers.dumpDom(selector?)` — returns a simplified DOM string
- `helpers.getStepOutput(order)` — returns the JSON-parsed `output` of a previous step. Positive values are absolute step orders; negative values are relative to the current step (`-1` = previous step).
Any value returned from `execCode` is JSON-serialised and stored as the `output` field on the `ScenarioRunStep` record. Subsequent steps can read it via `helpers.getStepOutput()`.
```js
// example execCode
await page.goto('https://cabinet.example.com/tasks/create/987825');
await page.locator('input[name="institution"]').fill('caltech');
await page.locator('button:has-text("Далі")').click();
await page.waitForLoadState('networkidle');
return page.url(); // stored in ScenarioRunStep.output
```
### `sign`
Performs EDS signing on the **current shared page** using a key from `KEYS_DIR`. The step clicks the sign widget, selects the file key method, uploads the key file, enters the password, and submits — all without requiring the step author to handle key material in their code.
`execCode` must be a JSON object:
```json
{ "keyId": "3137411915" }
```
## Validation code
Any step type optionally accepts `validateCode` — Playwright JS that runs on the shared page **after** the main action and must return a result evaluated as:
```js
return { success: true, description: 'Application created' };
// or
return { success: false, description: 'Expected success banner not found' };
// or simply
return someBoolean;
```
If `success` is false the step (and the whole run) fails with the provided `description`.
## Run statuses
`pending` → `in_progress` → `pass` | `fail`
Individual step runs also expose `waiting` (not yet reached) and `cancelled` (run failed before this step).
## Adding a new scenario (example workflow)
```
1. create_environment (if not already present)
2. create_scenario → get scenarioId
3. create_scenario_step type=login, order=0
4. create_scenario_step type=exec, order=1 (navigate + fill form)
5. create_scenario_step type=sign, order=2
6. create_scenario_step type=exec, order=3 (validateCode checks success banner)
7. run_scenario → get runId
8. wait_for_scenario_run (blocks until pass/fail, returns full run with outputs)
```
+2 -2
View File
@@ -1,12 +1,12 @@
{
"name": "liquio-qa-bot",
"version": "1.1.0",
"version": "1.2.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "liquio-qa-bot",
"version": "1.1.0",
"version": "1.2.0",
"license": "ISC",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.29.0",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "liquio-qa-bot",
"version": "1.1.0",
"version": "1.2.0",
"description": "",
"main": "index.js",
"scripts": {
+40
View File
@@ -0,0 +1,40 @@
{
"name": "Diia STG — Create certificate application (987825)",
"steps": [
{
"order": 0,
"type": "login",
"sessionName": "diia-stg-session",
"execCode": "{\"keyId\": \"3273334361\", \"environmentName\": \"liquio-diia-stg\"}",
"validateCode": null
},
{
"order": 1,
"type": "exec",
"sessionName": "diia-stg-session",
"execCode": "// Navigate to the tasks/services list for this user\nawait page.goto(\"https://cabinet-liquio-diia-stg.kitsoft.ua/tasks\", { waitUntil: \"networkidle\" });\nhelpers.log(\"URL: \" + page.url());\nhelpers.log(\"title: \" + await page.title());\n\nconst headings = await page.locator(\"h1, h2, h3\").allTextContents();\nhelpers.log(\"headings: \" + JSON.stringify(headings));\n\n// Find any links that look like task/service links\nconst links = await page.locator(\"a[href*=task], a[href*=service], a[href*=create]\").all();\nconst linkData = [];\nfor (const a of links.slice(0, 20)) {\n linkData.push({ href: await a.getAttribute(\"href\"), text: (await a.textContent()).trim().slice(0, 80) });\n}\nhelpers.log(\"task links: \" + JSON.stringify(linkData));\n\nconst bodyText = await page.locator(\"body\").innerText();\nhelpers.log(\"body (first 800): \" + bodyText.slice(0, 800));\n\nreturn page.url();\n",
"validateCode": null
},
{
"order": 2,
"type": "exec",
"sessionName": "diia-stg-session",
"execCode": "helpers.log(\"url=\" + page.url());\nconst btns = await page.locator(\"button\").all();\nconst labels = [];\nfor (const b of btns) { const t = (await b.textContent()) || \"\"; const vis = await b.isVisible(); if (vis) labels.push(t.trim()); }\nhelpers.log(\"visible buttons: \" + JSON.stringify(labels));\nreturn labels;",
"validateCode": null
},
{
"order": 3,
"type": "sign",
"sessionName": "diia-stg-session",
"execCode": "{\"keyId\": \"3273334361\"}",
"validateCode": null
},
{
"order": 4,
"type": "exec",
"sessionName": "diia-stg-session",
"execCode": "return page.url();",
"validateCode": "\nconst url = page.url();\nconst successEl = await page.locator('.success, [data-test=\"success\"], .task-success, .done-message').count();\nconst successText = /успішно|success|заяву подано|виконано/i.test(await page.locator('body').innerText());\nreturn {\n success: successEl > 0 || successText,\n description: `Final URL: ${url}`,\n};\n"
}
]
}
+4 -2
View File
@@ -1,5 +1,6 @@
import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { AppConfig, validateAppConfig } from "./config/app.config";
import { TypeOrmModule } from "@nestjs/typeorm";
import { ScheduleModule } from "@nestjs/schedule";
import { HealthModule } from "./health/health.module";
@@ -21,13 +22,14 @@ import { ScenarioModule } from "./scenario/scenario.module";
ConfigModule.forRoot({
isGlobal: true,
envFilePath: ".env",
validate: validateAppConfig,
}),
ScheduleModule.forRoot(),
TypeOrmModule.forRootAsync({
inject: [ConfigService],
useFactory: (config: ConfigService) => ({
useFactory: (config: ConfigService<AppConfig, true>) => ({
type: "better-sqlite3",
database: config.get<string>("DB_PATH", "data/sessions.db"),
database: config.get("DB_PATH"),
entities: [
SessionEntity,
EnvironmentEntity,
+15 -4
View File
@@ -6,12 +6,14 @@ import {
} from "@nestjs/common";
import { TraceLogger } from "../common/trace-logger";
import { ConfigService } from "@nestjs/config";
import { AppConfig } from "../config/app.config";
import { chromium } from "playwright";
import type { Page } from "playwright";
import * as fs from "fs";
import * as path from "path";
import * as crypto from "crypto";
import { SessionService } from "../session/session.service";
import { SessionContextService } from "../session/session-context.service";
import { EnvironmentService } from "../environment/environment.service";
interface KeyDescriptor {
@@ -26,11 +28,12 @@ export class AuthService {
private readonly keysDir: string;
constructor(
private readonly config: ConfigService,
private readonly config: ConfigService<AppConfig, true>,
private readonly sessionService: SessionService,
private readonly sessionContextService: SessionContextService,
private readonly environmentService: EnvironmentService,
) {
this.keysDir = path.resolve(this.config.get<string>("KEYS_DIR", "keys"));
this.keysDir = path.resolve(this.config.get("KEYS_DIR"));
}
listKeys(): string[] {
@@ -169,11 +172,21 @@ export class AuthService {
localStorageData,
);
// Register the live Playwright context — browser stays open for reuse
this.sessionContextService.register(
resolvedSession,
browser,
context,
page,
);
this.logger.log(
`Login successful for key ${keyId}, session: ${resolvedSession}`,
);
return { token, sessionName: resolvedSession };
} catch (err) {
// Close browser only on failure — on success it is kept alive in SessionContextService
await browser.close().catch(() => {});
if (
err instanceof BadRequestException ||
err instanceof InternalServerErrorException
@@ -185,8 +198,6 @@ export class AuthService {
`Login automation failed: ${(err as Error).message}`,
{ cause: err },
);
} finally {
await browser.close();
}
}
+61 -48
View File
@@ -2,14 +2,13 @@ import {
Injectable,
HttpException,
InternalServerErrorException,
NotFoundException,
} from "@nestjs/common";
import { TraceLogger } from "../common/trace-logger";
import { chromium } from "playwright";
import type { BrowserContext, Cookie } from "playwright";
import type { BrowserContext } from "playwright";
import { Readability } from "@mozilla/readability";
import { JSDOM } from "jsdom";
import { SessionService } from "../session/session.service";
import { SessionContextService } from "../session/session-context.service";
import { CodeExecutorService } from "../code-executor/code-executor.service";
import type { ExecResult } from "../code-executor/code-executor.service";
@@ -26,38 +25,10 @@ export class BrowserService {
private readonly logger = new TraceLogger(BrowserService.name);
constructor(
private readonly sessionService: SessionService,
private readonly sessionContextService: SessionContextService,
private readonly codeExecutor: CodeExecutorService,
) {}
private async setupSession(
context: BrowserContext,
sessionName: string | undefined,
): Promise<void> {
if (!sessionName) return;
const session = await this.sessionService.findBySessionName(sessionName);
if (!session) {
throw new NotFoundException(`Session not found: ${sessionName}`);
}
let cookies: Cookie[];
let localStorageData: Record<string, string>;
try {
cookies = JSON.parse(session.cookies);
localStorageData = JSON.parse(session.localStorage);
} catch (err) {
throw new InternalServerErrorException(
"Failed to deserialize session data",
{ cause: err },
);
}
await context.addCookies(cookies);
await context.addInitScript((entries: Record<string, string>) => {
for (const [k, v] of Object.entries(entries)) {
window.localStorage.setItem(k, v);
}
}, localStorageData);
}
private rethrow(err: unknown, label: string, operation: string): never {
if (err instanceof HttpException) {
throw err;
@@ -68,23 +39,15 @@ export class BrowserService {
);
}
async open(
sessionName: string | undefined,
private async extractContent(
context: BrowserContext,
url: string,
readerMode = false,
readerMode: boolean,
selector?: string,
): Promise<OpenResult> {
const label = sessionName ?? "anonymous";
const browser = await chromium.launch({
headless: true,
executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
});
const page = await context.newPage();
try {
const context = await browser.newContext();
await this.setupSession(context, sessionName);
const page = await context.newPage();
this.logger.log(`[${label}] Opening ${url}`);
this.logger.log(`Opening ${url}`);
await page.goto(url, { waitUntil: "networkidle" });
const finalUrl = page.url();
@@ -109,9 +72,41 @@ export class BrowserService {
}
this.logger.log(
`[${label}] Loaded: ${finalUrl} — "${title}"${readerMode ? " (reader mode)" : ""}${selector ? ` (selector: ${selector})` : ""}`,
`Loaded: ${finalUrl} — "${title}"${readerMode ? " (reader mode)" : ""}${selector ? ` (selector: ${selector})` : ""}`,
);
return { url: finalUrl, title, content };
} finally {
await page.close();
}
}
async open(
sessionName: string | undefined,
url: string,
readerMode = false,
selector?: string,
): Promise<OpenResult> {
const label = sessionName ?? "anonymous";
this.logger.log(`[${label}] open: ${url}`);
if (sessionName) {
const { context } =
await this.sessionContextService.getHandle(sessionName);
try {
return await this.extractContent(context, url, readerMode, selector);
} catch (err) {
this.rethrow(err, label, "open");
}
}
// Anonymous — ephemeral browser
const browser = await chromium.launch({
headless: true,
executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
});
try {
const context = await browser.newContext();
return await this.extractContent(context, url, readerMode, selector);
} catch (err) {
this.rethrow(err, label, "open");
} finally {
@@ -125,13 +120,32 @@ export class BrowserService {
url?: string,
): Promise<ExecResult> {
const label = sessionName ?? "anonymous";
if (sessionName) {
const { page, context } =
await this.sessionContextService.getHandle(sessionName);
this.logger.log(`[${label}] exec: using persistent context`);
try {
if (url) {
this.logger.log(`[${label}] exec: navigating to ${url}`);
await page.goto(url, { waitUntil: "networkidle" });
}
this.logger.log(`[${label}] exec: running user code`);
const result = await this.codeExecutor.execute(page, context, code);
this.logger.log(`[${label}] exec: done`);
return result;
} catch (err) {
this.rethrow(err, label, "exec");
}
}
// Anonymous — ephemeral browser
const browser = await chromium.launch({
headless: true,
executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH,
});
try {
const context = await browser.newContext();
await this.setupSession(context, sessionName);
const page = await context.newPage();
if (url) {
@@ -141,7 +155,6 @@ export class BrowserService {
this.logger.log(`[${label}] exec: running user code`);
const result = await this.codeExecutor.execute(page, context, code);
this.logger.log(`[${label}] exec: done`);
return result;
} catch (err) {
@@ -46,6 +46,7 @@ export class CodeExecutorService {
context: BrowserContext,
code: string,
log?: ScriptLogger,
getStepOutput?: (order: number) => Promise<unknown>,
): Promise<ExecResult> {
const scriptLog: ScriptLogger =
log ?? ((level, msg) => this.logger[level](msg));
@@ -60,6 +61,7 @@ export class CodeExecutorService {
log: (...args: unknown[]) => scriptLog("log", toStr(args)),
warn: (...args: unknown[]) => scriptLog("warn", toStr(args)),
error: (...args: unknown[]) => scriptLog("error", toStr(args)),
getStepOutput: getStepOutput ?? (() => Promise.resolve(null)),
};
const fakeConsole = {
+27
View File
@@ -1,4 +1,6 @@
import { IsInt, IsString, Min, Max } from "class-validator";
import { plainToInstance } from "class-transformer";
import { validateSync } from "class-validator";
import pkg from "../../package.json";
@@ -16,4 +18,29 @@ export class AppConfig {
@IsString()
APP_VERSION: string = pkg.version;
@IsString()
KEYS_DIR: string = "keys";
@IsString()
DB_PATH: string = "data/sessions.db";
@IsInt()
@Min(1)
SESSION_IDLE_TIMEOUT_MINUTES: number = 30;
@IsInt()
@Min(1)
SESSION_DELETE_CLOSED_DAYS: number = 7;
}
export function validateAppConfig(config: Record<string, unknown>): AppConfig {
const validated = plainToInstance(AppConfig, config, {
enableImplicitConversion: true,
});
const errors = validateSync(validated, { skipMissingProperties: false });
if (errors.length > 0) {
throw new Error(errors.toString());
}
return validated;
}
+4 -3
View File
@@ -1,5 +1,6 @@
import { NestFactory } from "@nestjs/core";
import { ConfigService } from "@nestjs/config";
import { AppConfig } from "./config/app.config";
import { ValidationPipe } from "@nestjs/common";
import { TraceLogger } from "./common/trace-logger";
import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
@@ -19,9 +20,9 @@ async function bootstrap() {
app.useGlobalFilters(new HttpExceptionFilter());
app.useGlobalInterceptors(new TraceInterceptor(), new LoggingInterceptor());
const config = app.get(ConfigService);
const port = config.get<number>("PORT", 3000);
const nodeEnv = config.get<string>("NODE_ENV", "development");
const config = app.get<ConfigService<AppConfig, true>>(ConfigService);
const port = config.get("PORT");
const nodeEnv = config.get("NODE_ENV");
const swaggerConfig = new DocumentBuilder()
.setTitle(pkgName)
+141 -8
View File
@@ -5,6 +5,7 @@ import { z } from "zod";
import type { Request, Response } from "express";
import { AuthService } from "../auth/auth.service";
import { SessionService } from "../session/session.service";
import { SessionContextService } from "../session/session-context.service";
import { EnvironmentService } from "../environment/environment.service";
import type { EnvironmentUrls } from "../environment/environment.entity";
import { BrowserService } from "../browser/browser.service";
@@ -18,6 +19,7 @@ export class McpService {
constructor(
private readonly authService: AuthService,
private readonly sessionService: SessionService,
private readonly sessionContextService: SessionContextService,
private readonly environmentService: EnvironmentService,
private readonly browserService: BrowserService,
private readonly codeExecutor: CodeExecutorService,
@@ -99,7 +101,14 @@ export class McpService {
.optional()
.describe("Items per page (default 20)"),
orderBy: z
.enum(["id", "sessionName", "createdAt", "updatedAt"])
.enum([
"id",
"sessionName",
"status",
"lastUsedAt",
"createdAt",
"updatedAt",
])
.optional()
.describe("Field to order by (default id)"),
orderDir: z
@@ -124,22 +133,20 @@ export class McpService {
server.registerTool(
"delete_session",
{
description: "Delete a session by numeric ID",
description: "Delete a session by numeric ID (closes it first if open)",
inputSchema: {
id: z.number().int().describe("Session ID to delete"),
},
},
async ({ id }) => {
const { data } = await this.sessionService.findAll();
if (!data.find((s) => s.id === id)) {
try {
await this.sessionContextService.delete(id);
} catch (err) {
return {
isError: true,
content: [
{ type: "text" as const, text: `Session ${id} not found` },
],
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
await this.sessionService.remove(id);
return {
content: [{ type: "text" as const, text: `Session ${id} deleted` }],
};
@@ -731,6 +738,132 @@ export class McpService {
},
);
server.registerTool(
"get_scenario_run",
{
description:
"Get a specific scenario run with all step runs and their outputs",
inputSchema: {
scenarioId: z.number().int().describe("Scenario ID"),
runId: z.number().int().describe("Run ID"),
},
},
async ({ scenarioId, runId }) => {
try {
const run = await this.scenarioService.findRun(scenarioId, runId);
return {
content: [{ type: "text" as const, text: JSON.stringify(run) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"wait_for_scenario_run",
{
description:
"Block until a scenario run reaches pass or fail (max 5 min), then return the full run with step outputs",
inputSchema: {
scenarioId: z.number().int().describe("Scenario ID"),
runId: z.number().int().describe("Run ID"),
},
},
async ({ scenarioId, runId }) => {
try {
const run = await this.scenarioService.waitForRun(scenarioId, runId);
return {
content: [{ type: "text" as const, text: JSON.stringify(run) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"export_scenario",
{
description:
"Export a scenario as a portable JSON payload (name + steps)",
inputSchema: {
id: z.number().int().describe("Scenario ID to export"),
},
},
async ({ id }) => {
try {
const exported = await this.scenarioService.exportScenario(id);
return {
content: [
{ type: "text" as const, text: JSON.stringify(exported) },
],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"import_scenario",
{
description:
"Import a scenario from an export payload, creating a new scenario with all its steps",
inputSchema: {
name: z.string().describe("Scenario name"),
steps: z
.array(
z.object({
order: z.number().int().min(0).describe("Execution order"),
type: z.enum(["login", "exec", "sign"]).describe("Step type"),
sessionName: z.string().describe("Session name"),
execCode: z
.string()
.nullable()
.optional()
.describe("Exec/sign code"),
validateCode: z
.string()
.nullable()
.optional()
.describe("Validation code"),
}),
)
.describe("Ordered list of steps"),
},
},
async ({ name, steps }) => {
try {
const scenario = await this.scenarioService.importScenario({
name,
steps: steps as Parameters<
typeof this.scenarioService.importScenario
>[0]["steps"],
});
return {
content: [
{ type: "text" as const, text: JSON.stringify(scenario) },
],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
// ── Transport ─────────────────────────────────────────────────────────────
}
+3
View File
@@ -48,6 +48,9 @@ export class ScenarioRunStepEntity {
@Column({ type: "text", nullable: true })
description: string | null;
@Column({ type: "text", nullable: true })
output: string | null;
@CreateDateColumn()
createdAt: Date;
+28 -2
View File
@@ -63,6 +63,24 @@ export class ScenarioSchedulerService {
};
}
private makeGetStepOutput(
stepRun: ScenarioRunStepEntity,
): (order: number) => Promise<unknown> {
return async (order: number) => {
const targetOrder = order < 0 ? stepRun.order + order : order;
if (targetOrder < 0) return null;
const sr = await this.runStepRepo.findOne({
where: { runId: stepRun.runId, order: targetOrder },
});
if (!sr?.output) return null;
try {
return JSON.parse(sr.output) as unknown;
} catch {
return sr.output;
}
};
}
// ── Job: pick up pending runs and process each to completion ─────────────
@Interval(1000)
@@ -223,6 +241,7 @@ export class ScenarioSchedulerService {
context,
step.validateCode,
this.stepLogger(stepRun.id, stepRun.runId),
this.makeGetStepOutput(stepRun),
);
const vr = this.parseValidateResult(result);
if (!vr.success) throw new Error(vr.description ?? "Validation failed");
@@ -244,11 +263,13 @@ export class ScenarioSchedulerService {
stepRun.runId,
step.sessionName,
);
await this.codeExecutor.execute(
const getStepOutput = this.makeGetStepOutput(stepRun);
const { result: execOutput } = await this.codeExecutor.execute(
page,
context,
step.execCode,
this.stepLogger(stepRun.id, stepRun.runId),
getStepOutput,
);
this.logger.log(`StepRun #${stepRun.id}: exec OK`);
@@ -259,12 +280,13 @@ export class ScenarioSchedulerService {
context,
step.validateCode,
this.stepLogger(stepRun.id, stepRun.runId),
getStepOutput,
);
const vr = this.parseValidateResult(result);
if (!vr.success) throw new Error(vr.description ?? "Validation failed");
}
await this.passStepRun(stepRun, null);
await this.passStepRun(stepRun, null, execOutput);
}
// ── Sign step ──────────────────────────────────────────────────────────────
@@ -296,6 +318,7 @@ export class ScenarioSchedulerService {
context,
step.validateCode,
this.stepLogger(stepRun.id, stepRun.runId),
this.makeGetStepOutput(stepRun),
);
const vr = this.parseValidateResult(result);
if (!vr.success) throw new Error(vr.description ?? "Validation failed");
@@ -324,9 +347,12 @@ export class ScenarioSchedulerService {
private async passStepRun(
stepRun: ScenarioRunStepEntity,
description: string | null,
output: unknown = null,
): Promise<void> {
stepRun.status = "pass";
stepRun.description = description;
stepRun.output =
output !== null && output !== undefined ? JSON.stringify(output) : null;
await this.runStepRepo.save(stepRun);
this.logger.log(`StepRun #${stepRun.id} → pass`);
+132
View File
@@ -0,0 +1,132 @@
import {
Injectable,
OnModuleDestroy,
BadRequestException,
NotFoundException,
} from "@nestjs/common";
import type { Browser, BrowserContext, Page } from "playwright";
import { TraceLogger } from "../common/trace-logger";
import { SessionService } from "./session.service";
export interface SessionHandle {
browser: Browser;
context: BrowserContext;
page: Page;
}
/**
* Keeps live Playwright browser contexts in memory, keyed by sessionName.
* A session must be explicitly registered (after login) to be usable.
* Sessions marked as closed in the DB cannot be used via getHandle().
*/
@Injectable()
export class SessionContextService implements OnModuleDestroy {
private readonly logger = new TraceLogger(SessionContextService.name);
private readonly handles = new Map<string, SessionHandle>();
constructor(private readonly sessionService: SessionService) {}
/**
* Store a live browser context after a successful login.
* If a handle already exists for this session it is closed first.
*/
register(
sessionName: string,
browser: Browser,
context: BrowserContext,
page: Page,
): void {
const existing = this.handles.get(sessionName);
if (existing) {
existing.browser.close().catch((err: unknown) => {
this.logger.warn(
`Error closing stale browser for "${sessionName}": ${(err as Error).message}`,
);
});
}
this.handles.set(sessionName, { browser, context, page });
this.logger.log(`Session "${sessionName}" registered in context pool`);
}
/**
* Return the live handle for a named session and bump lastUsedAt.
* Throws 404 if session does not exist in DB.
* Throws 400 if session is closed or context is not in memory.
*/
async getHandle(sessionName: string): Promise<SessionHandle> {
const handle = this.handles.get(sessionName);
if (handle) {
await this.sessionService.touchLastUsed(sessionName);
return handle;
}
const session = await this.sessionService.findBySessionName(sessionName);
if (!session) {
throw new NotFoundException(`Session not found: ${sessionName}`);
}
if (session.status === "closed") {
throw new BadRequestException(
`Session "${sessionName}" is closed — please login again`,
);
}
// Session is open in DB but context is not in memory (e.g. after unexpected restart).
throw new BadRequestException(
`Session "${sessionName}" context is not available — please login again`,
);
}
/**
* Close the Playwright browser for a session and mark it as closed in DB.
* Safe to call even if the session is not currently in memory.
*/
async close(sessionName: string): Promise<void> {
const handle = this.handles.get(sessionName);
if (handle) {
try {
await handle.browser.close();
} catch (err) {
this.logger.warn(
`Error closing browser for session "${sessionName}": ${(err as Error).message}`,
);
}
this.handles.delete(sessionName);
}
await this.sessionService.markClosed(sessionName);
this.logger.log(`Session "${sessionName}" closed`);
}
/**
* Close all in-memory handles and mark every open session as closed in DB.
*/
async closeAll(): Promise<void> {
const names = Array.from(this.handles.keys());
await Promise.allSettled(names.map((name) => this.close(name)));
if (names.length > 0) {
this.logger.log(`Closed ${names.length} session context(s)`);
}
}
/**
* Close the context (if open) and delete the session record from DB.
* Throws 404 if the session ID does not exist.
*/
async delete(id: number): Promise<void> {
const session = await this.sessionService.findById(id);
if (!session) {
throw new NotFoundException(`Session ${id} not found`);
}
if (this.handles.has(session.sessionName)) {
await this.close(session.sessionName);
}
await this.sessionService.remove(id);
}
/** Returns true if a live Playwright context exists for this session. */
isOpen(sessionName: string): boolean {
return this.handles.has(sessionName);
}
async onModuleDestroy(): Promise<void> {
await this.closeAll();
}
}
+53
View File
@@ -0,0 +1,53 @@
import { Injectable } from "@nestjs/common";
import { Interval } from "@nestjs/schedule";
import { ConfigService } from "@nestjs/config";
import { AppConfig } from "../config/app.config";
import { TraceLogger } from "../common/trace-logger";
import { SessionService } from "./session.service";
import { SessionContextService } from "./session-context.service";
/**
* Periodically:
* 1. Closes sessions that have been idle for longer than SESSION_IDLE_TIMEOUT_MINUTES.
* 2. Deletes closed sessions whose updatedAt is older than SESSION_DELETE_CLOSED_DAYS.
*/
@Injectable()
export class SessionSchedulerService {
private readonly logger = new TraceLogger(SessionSchedulerService.name);
constructor(
private readonly sessionService: SessionService,
private readonly sessionContextService: SessionContextService,
private readonly config: ConfigService<AppConfig, true>,
) {}
@Interval(60_000)
async runScheduler(): Promise<void> {
await this.closeExpired();
await this.deleteOldClosed();
}
private async closeExpired(): Promise<void> {
const idleMinutes = this.config.get("SESSION_IDLE_TIMEOUT_MINUTES");
const cutoff = new Date(Date.now() - idleMinutes * 60_000);
const expired = await this.sessionService.findExpiredOpen(cutoff);
for (const session of expired) {
await this.sessionContextService.close(session.sessionName);
this.logger.log(
`Session "${session.sessionName}" closed (idle > ${idleMinutes} min)`,
);
}
}
private async deleteOldClosed(): Promise<void> {
const days = this.config.get("SESSION_DELETE_CLOSED_DAYS");
const cutoff = new Date(Date.now() - days * 86_400_000);
const old = await this.sessionService.findOldClosed(cutoff);
for (const session of old) {
await this.sessionService.remove(session.id);
this.logger.log(
`Session "${session.sessionName}" deleted (closed > ${days} days ago)`,
);
}
}
}
+7 -8
View File
@@ -2,20 +2,23 @@ import {
Controller,
Delete,
Get,
NotFoundException,
Param,
ParseIntPipe,
Query,
} from "@nestjs/common";
import { ApiOperation, ApiResponse, ApiTags } from "@nestjs/swagger";
import { SessionService } from "./session.service";
import { SessionContextService } from "./session-context.service";
import { PaginationQueryDto } from "../common/dto/pagination.dto";
import { SessionOrderBy } from "./session.service";
@ApiTags("sessions")
@Controller("sessions")
export class SessionController {
constructor(private readonly sessionService: SessionService) {}
constructor(
private readonly sessionService: SessionService,
private readonly sessionContextService: SessionContextService,
) {}
@Get()
@ApiOperation({ summary: "List all stored sessions (paginated)" })
@@ -25,14 +28,10 @@ export class SessionController {
}
@Delete(":id")
@ApiOperation({ summary: "Delete a session by ID" })
@ApiOperation({ summary: "Delete a session by ID (closes it first if open)" })
@ApiResponse({ status: 200, description: "Session deleted" })
@ApiResponse({ status: 404, description: "Session not found" })
async remove(@Param("id", ParseIntPipe) id: number): Promise<void> {
const sessions = await this.sessionService.findAll();
if (!sessions.data.find((s) => s.id === id)) {
throw new NotFoundException(`Session ${id} not found`);
}
await this.sessionService.remove(id);
await this.sessionContextService.delete(id);
}
}
+8
View File
@@ -6,6 +6,8 @@ import {
UpdateDateColumn,
} from "typeorm";
export type SessionStatus = "open" | "closed";
@Entity("sessions")
export class SessionEntity {
@PrimaryGeneratedColumn()
@@ -23,6 +25,12 @@ export class SessionEntity {
@Column("text", { default: "{}" })
localStorage: string; // JSON-serialised Record<string, string> from Playwright
@Column({ default: "closed" })
status: SessionStatus;
@Column({ type: "datetime", nullable: true, default: null })
lastUsedAt: Date | null;
@CreateDateColumn()
createdAt: Date;
+4 -2
View File
@@ -3,11 +3,13 @@ import { TypeOrmModule } from "@nestjs/typeorm";
import { SessionEntity } from "./session.entity";
import { SessionService } from "./session.service";
import { SessionController } from "./session.controller";
import { SessionContextService } from "./session-context.service";
import { SessionSchedulerService } from "./session-scheduler.service";
@Module({
imports: [TypeOrmModule.forFeature([SessionEntity])],
controllers: [SessionController],
providers: [SessionService],
exports: [SessionService],
providers: [SessionService, SessionContextService, SessionSchedulerService],
exports: [SessionService, SessionContextService],
})
export class SessionModule {}
+77 -6
View File
@@ -1,34 +1,58 @@
import { Injectable } from "@nestjs/common";
import { Injectable, OnApplicationBootstrap } from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm";
import { Repository } from "typeorm";
import { LessThan, Repository } from "typeorm";
import { SessionEntity } from "./session.entity";
import { TraceLogger } from "../common/trace-logger";
import type { Cookie } from "playwright";
import {
PaginationQueryDto,
PaginatedResult,
} from "../common/dto/pagination.dto";
export type SessionOrderBy = "id" | "sessionName" | "createdAt" | "updatedAt";
export type SessionOrderBy =
| "id"
| "sessionName"
| "status"
| "lastUsedAt"
| "createdAt"
| "updatedAt";
@Injectable()
export class SessionService {
export class SessionService implements OnApplicationBootstrap {
private readonly logger = new TraceLogger(SessionService.name);
constructor(
@InjectRepository(SessionEntity)
private readonly repo: Repository<SessionEntity>,
) {}
async onApplicationBootstrap(): Promise<void> {
const result = await this.repo.update(
{ status: "open" },
{ status: "closed" },
);
if ((result.affected ?? 0) > 0) {
this.logger.log(
`${result.affected} open session(s) closed on startup (no Playwright context available)`,
);
}
}
async upsert(
sessionName: string,
token: string,
cookies: Cookie[],
localStorage: Record<string, string>,
): Promise<SessionEntity> {
const now = new Date();
const existing = await this.repo.findOneBy({ sessionName });
if (existing) {
existing.token = token;
existing.cookies = JSON.stringify(cookies);
existing.localStorage = JSON.stringify(localStorage);
existing.status = "open";
existing.lastUsedAt = now;
return this.repo.save(existing);
}
@@ -38,6 +62,8 @@ export class SessionService {
token,
cookies: JSON.stringify(cookies),
localStorage: JSON.stringify(localStorage),
status: "open",
lastUsedAt: now,
}),
);
}
@@ -46,11 +72,49 @@ export class SessionService {
return this.repo.findOneBy({ sessionName });
}
findById(id: number): Promise<SessionEntity | null> {
return this.repo.findOneBy({ id });
}
async markOpen(sessionName: string): Promise<void> {
await this.repo.update({ sessionName }, { status: "open" });
}
async markClosed(sessionName: string): Promise<void> {
await this.repo.update({ sessionName }, { status: "closed" });
}
async touchLastUsed(sessionName: string): Promise<void> {
await this.repo.update({ sessionName }, { lastUsedAt: new Date() });
}
findExpiredOpen(cutoff: Date): Promise<SessionEntity[]> {
return this.repo
.createQueryBuilder("s")
.where("s.status = :status", { status: "open" })
.andWhere("(s.lastUsedAt IS NULL OR s.lastUsedAt < :cutoff)", { cutoff })
.getMany();
}
findOldClosed(cutoff: Date): Promise<SessionEntity[]> {
return this.repo.find({
where: { status: "closed", updatedAt: LessThan(cutoff) },
});
}
async findAll(
query: PaginationQueryDto<SessionOrderBy> = {},
): Promise<
PaginatedResult<
Pick<SessionEntity, "id" | "sessionName" | "createdAt" | "updatedAt">
Pick<
SessionEntity,
| "id"
| "sessionName"
| "status"
| "lastUsedAt"
| "createdAt"
| "updatedAt"
>
>
> {
const page = query.page ?? 1;
@@ -58,7 +122,14 @@ export class SessionService {
const orderBy = query.orderBy ?? "id";
const orderDir = query.orderDir ?? "ASC";
const [data, total] = await this.repo.findAndCount({
select: ["id", "sessionName", "createdAt", "updatedAt"],
select: [
"id",
"sessionName",
"status",
"lastUsedAt",
"createdAt",
"updatedAt",
],
order: { [orderBy]: orderDir },
skip: (page - 1) * limit,
take: limit,
+23 -13
View File
@@ -1,15 +1,25 @@
const makePage = () => ({
goto: jest.fn(),
content: jest.fn().mockResolvedValue("<html></html>"),
title: jest.fn().mockReturnValue(""),
url: jest.fn().mockReturnValue(""),
evaluate: jest.fn(),
close: jest.fn(),
});
const makeContext = () => ({
newPage: jest.fn().mockResolvedValue(makePage()),
addCookies: jest.fn().mockResolvedValue(undefined),
addInitScript: jest.fn().mockResolvedValue(undefined),
});
const makeBrowser = () => ({
newContext: jest
.fn()
.mockImplementation(() => Promise.resolve(makeContext())),
close: jest.fn(),
});
export const chromium = {
launch: jest.fn().mockResolvedValue({
newContext: jest.fn().mockResolvedValue({
newPage: jest.fn().mockResolvedValue({
goto: jest.fn(),
content: jest.fn().mockResolvedValue("<html></html>"),
title: jest.fn().mockReturnValue(""),
url: jest.fn().mockReturnValue(""),
evaluate: jest.fn(),
close: jest.fn(),
}),
}),
close: jest.fn(),
}),
launch: jest.fn().mockImplementation(() => Promise.resolve(makeBrowser())),
};
+6 -1
View File
@@ -45,11 +45,16 @@ import { ScenarioRunLogEntity } from "../src/scenario/scenario-run-log.entity";
import { HealthController } from "../src/health/health.controller";
import { HttpExceptionFilter } from "../src/filters/http-exception.filter";
import { LoggingInterceptor } from "../src/interceptors/logging.interceptor";
import { validateAppConfig } from "../src/config/app.config";
export async function buildTestApp(): Promise<INestApplication> {
const module: TestingModule = await Test.createTestingModule({
imports: [
ConfigModule.forRoot({ isGlobal: true, ignoreEnvFile: true }),
ConfigModule.forRoot({
isGlobal: true,
ignoreEnvFile: true,
validate: validateAppConfig,
}),
TypeOrmModule.forRoot({
type: "better-sqlite3",
database: ":memory:",
+12 -10
View File
@@ -139,16 +139,18 @@ function makePage(rootEl: FakeEl) {
const evaluate = jest
.fn()
.mockImplementation((fn: (...args: unknown[]) => unknown, args: unknown) => {
const exec = new Function(
"document",
"window",
"Node",
"__args__",
`return (${fn.toString()})(__args__)`,
);
return Promise.resolve(exec(fakeDocument, fakeWindow, fakeNode, args));
});
.mockImplementation(
(fn: (...args: unknown[]) => unknown, args: unknown) => {
const exec = new Function(
"document",
"window",
"Node",
"__args__",
`return (${fn.toString()})(__args__)`,
);
return Promise.resolve(exec(fakeDocument, fakeWindow, fakeNode, args));
},
);
return { evaluate } as unknown as import("playwright").Page;
}
+6 -2
View File
@@ -117,7 +117,9 @@ describe("EnvironmentController", () => {
const res = await request(app.getHttpServer())
.get("/environments?orderBy=name&orderDir=ASC")
.expect(200);
const names: string[] = res.body.data.map((e: { name: string }) => e.name);
const names: string[] = res.body.data.map(
(e: { name: string }) => e.name,
);
expect(names).toEqual([...names].sort());
});
@@ -125,7 +127,9 @@ describe("EnvironmentController", () => {
const res = await request(app.getHttpServer())
.get("/environments?orderBy=name&orderDir=DESC")
.expect(200);
const names: string[] = res.body.data.map((e: { name: string }) => e.name);
const names: string[] = res.body.data.map(
(e: { name: string }) => e.name,
);
expect(names).toEqual([...names].sort().reverse());
});
+204
View File
@@ -0,0 +1,204 @@
/**
* Integration tests for ScenarioRunStepEntity.output column and the
* helpers.getStepOutput() API available inside exec step scripts.
*
* Strategy:
* - Seed a session row so the scheduler can create a browser context.
* - Create a scenario + steps with controlled return values.
* - Call ScenarioSchedulerService.pickUpPendingRuns() directly to process
* the run synchronously (no real timers needed).
* - Assert step-run output persisted and getStepOutput() returns it.
*/
import { INestApplication } from "@nestjs/common";
import { DataSource } from "typeorm";
import { buildTestApp } from "./app.harness";
import { ScenarioService } from "../src/scenario/scenario.service";
import { ScenarioSchedulerService } from "../src/scenario/scenario-scheduler.service";
describe("ScenarioRunStepEntity.output + helpers.getStepOutput", () => {
let app: INestApplication;
let dataSource: DataSource;
let scenarioService: ScenarioService;
let scheduler: ScenarioSchedulerService;
beforeAll(async () => {
app = await buildTestApp();
dataSource = app.get(DataSource);
scenarioService = app.get(ScenarioService);
scheduler = app.get(ScenarioSchedulerService);
});
afterAll(async () => {
await app.close();
});
/** Seed a minimal session so the scheduler can open a browser context. */
async function seedSession(name = "output-test-session"): Promise<void> {
await dataSource.query(
`INSERT OR IGNORE INTO sessions (sessionName, token, cookies, localStorage)
VALUES ('${name}', 'tok', '[]', '{}')`,
);
}
/** Create a scenario and return its id. */
async function createScenario(name = "output-scenario"): Promise<number> {
const sc = await scenarioService.create({ name });
return sc.id;
}
/** Create a step and return its id. */
async function createStep(
scenarioId: number,
order: number,
execCode: string,
sessionName = "output-test-session",
): Promise<number> {
const step = await scenarioService.createStep(scenarioId, {
order,
type: "exec",
sessionName,
execCode,
});
return step.id;
}
/** Trigger a run and process it to completion via the scheduler. */
async function runScenario(scenarioId: number): Promise<number> {
const run = await scenarioService.createRun(scenarioId);
// Drive the scheduler directly — keeps tests synchronous and fast.
await scheduler.pickUpPendingRuns();
// Wait for the run to reach a terminal state (max 10 s).
const result = await scenarioService.waitForRun(scenarioId, run.id, 10_000);
return result.id;
}
// ── output column ──────────────────────────────────────────────────────────
describe("output column", () => {
it("stores the return value of an exec script as JSON", async () => {
await seedSession();
const scId = await createScenario("output-basic");
await createStep(scId, 0, "return 42;");
const runId = await runScenario(scId);
const row = await dataSource.query(
`SELECT output, status FROM scenario_run_steps WHERE runId = ${runId}`,
);
expect(row[0].status).toBe("pass");
expect(JSON.parse(row[0].output as string)).toBe(42);
});
it("stores object return values as JSON", async () => {
await seedSession();
const scId = await createScenario("output-object");
await createStep(scId, 0, 'return { foo: "bar", n: 7 };');
const runId = await runScenario(scId);
const row = await dataSource.query(
`SELECT output FROM scenario_run_steps WHERE runId = ${runId}`,
);
expect(JSON.parse(row[0].output as string)).toEqual({ foo: "bar", n: 7 });
});
it("stores null when the script returns undefined/nothing", async () => {
await seedSession();
const scId = await createScenario("output-undefined");
await createStep(scId, 0, "const x = 1;");
const runId = await runScenario(scId);
const row = await dataSource.query(
`SELECT output FROM scenario_run_steps WHERE runId = ${runId}`,
);
expect(row[0].output).toBeNull();
});
it("output is exposed on the stepRuns inside GET /scenarios/:id/run/:runId via findRun", async () => {
await seedSession();
const scId = await createScenario("output-findrun");
await createStep(scId, 0, "return 'hello';");
const runId = await runScenario(scId);
const run = await scenarioService.findRun(scId, runId);
expect(run.stepRuns[0].output).toBe(JSON.stringify("hello"));
});
});
// ── helpers.getStepOutput ──────────────────────────────────────────────────
describe("helpers.getStepOutput()", () => {
it("returns output of a previous step by absolute order", async () => {
await seedSession();
const scId = await createScenario("getStepOutput-absolute");
await createStep(scId, 0, "return 99;");
// Step 1 reads step 0's output via absolute index 0
await createStep(scId, 1, "return await helpers.getStepOutput(0);");
const runId = await runScenario(scId);
const rows = await dataSource.query(
`SELECT "order", output FROM scenario_run_steps WHERE runId = ${runId} ORDER BY "order"`,
);
expect(JSON.parse(rows[0].output as string)).toBe(99);
expect(JSON.parse(rows[1].output as string)).toBe(99);
});
it("returns output of the previous step using relative index -1", async () => {
await seedSession();
const scId = await createScenario("getStepOutput-relative");
await createStep(scId, 0, 'return "step-zero";');
// Step 1 uses relative index -1 to reference step 0
await createStep(scId, 1, "return await helpers.getStepOutput(-1);");
const runId = await runScenario(scId);
const rows = await dataSource.query(
`SELECT "order", output FROM scenario_run_steps WHERE runId = ${runId} ORDER BY "order"`,
);
expect(JSON.parse(rows[1].output as string)).toBe("step-zero");
});
it("returns null for a step that does not exist", async () => {
await seedSession();
const scId = await createScenario("getStepOutput-missing");
// Step 0 tries to read step order 99 which does not exist
await createStep(scId, 0, "return await helpers.getStepOutput(99);");
const runId = await runScenario(scId);
const row = await dataSource.query(
`SELECT output FROM scenario_run_steps WHERE runId = ${runId}`,
);
expect(row[0].output).toBeNull();
});
it("chains output across three steps", async () => {
await seedSession();
const scId = await createScenario("getStepOutput-chain");
await createStep(scId, 0, "return [1, 2];");
await createStep(
scId,
1,
"const prev = await helpers.getStepOutput(-1); return [...prev, 3];",
);
await createStep(
scId,
2,
"const prev = await helpers.getStepOutput(-1); return [...prev, 4];",
);
const runId = await runScenario(scId);
const rows = await dataSource.query(
`SELECT "order", output FROM scenario_run_steps WHERE runId = ${runId} ORDER BY "order"`,
);
expect(JSON.parse(rows[0].output as string)).toEqual([1, 2]);
expect(JSON.parse(rows[1].output as string)).toEqual([1, 2, 3]);
expect(JSON.parse(rows[2].output as string)).toEqual([1, 2, 3, 4]);
});
});
});
+9 -3
View File
@@ -106,7 +106,9 @@ describe("ScenarioController", () => {
const res = await request(app.getHttpServer())
.get("/scenarios?orderBy=name&orderDir=ASC")
.expect(200);
const names: string[] = res.body.data.map((s: { name: string }) => s.name);
const names: string[] = res.body.data.map(
(s: { name: string }) => s.name,
);
expect(names).toEqual([...names].sort());
});
@@ -114,7 +116,9 @@ describe("ScenarioController", () => {
const res = await request(app.getHttpServer())
.get("/scenarios?orderBy=name&orderDir=DESC")
.expect(200);
const names: string[] = res.body.data.map((s: { name: string }) => s.name);
const names: string[] = res.body.data.map(
(s: { name: string }) => s.name,
);
expect(names).toEqual([...names].sort().reverse());
});
@@ -336,7 +340,9 @@ describe("ScenarioController", () => {
expect(Array.isArray(res.body.stepRuns)).toBe(true);
expect(res.body.stepRuns).toHaveLength(3);
const statuses = res.body.stepRuns.map((s: { status: string }) => s.status);
const statuses = res.body.stepRuns.map(
(s: { status: string }) => s.status,
);
expect(statuses[0]).toBe("pending");
expect(statuses[1]).toBe("waiting");
expect(statuses[2]).toBe("waiting");
+12 -4
View File
@@ -49,7 +49,9 @@ describe("SessionController", () => {
const res = await request(app.getHttpServer())
.get("/sessions")
.expect(200);
const names = res.body.data.map((s: { sessionName: string }) => s.sessionName);
const names = res.body.data.map(
(s: { sessionName: string }) => s.sessionName,
);
expect(names).toContain("visible-session");
});
@@ -97,7 +99,9 @@ describe("SessionController", () => {
const res = await request(app.getHttpServer())
.get("/sessions?orderBy=sessionName&orderDir=ASC")
.expect(200);
const names: string[] = res.body.data.map((s: { sessionName: string }) => s.sessionName);
const names: string[] = res.body.data.map(
(s: { sessionName: string }) => s.sessionName,
);
expect(names).toEqual([...names].sort());
});
@@ -105,7 +109,9 @@ describe("SessionController", () => {
const res = await request(app.getHttpServer())
.get("/sessions?orderBy=sessionName&orderDir=DESC")
.expect(200);
const names: string[] = res.body.data.map((s: { sessionName: string }) => s.sessionName);
const names: string[] = res.body.data.map(
(s: { sessionName: string }) => s.sessionName,
);
expect(names).toEqual([...names].sort().reverse());
});
@@ -128,7 +134,9 @@ describe("SessionController", () => {
const res = await request(app.getHttpServer())
.get("/sessions")
.expect(200);
const names = res.body.data.map((sess: { sessionName: string }) => sess.sessionName);
const names = res.body.data.map(
(sess: { sessionName: string }) => sess.sessionName,
);
expect(names).not.toContain("delete-me-session");
});