feat(versioning): version scenarios and snippets, bump to 1.16.0

- snapshot scenario and snippet content into version tables on every
  content change; live tables keep holding the latest version
- record the scenario version on each run and copy its steps into the
  run steps, so runs execute and show the version they were created with
- keep run step history when a step is deleted (FK set null)
- pin a snippet version with runSnippet('alias@N')
- add version picker to the run modal and version info across the UI
- add version list/get endpoints and MCP tools
- include version in exports and require it on import, restoring the
  exact version by id + version
This commit is contained in:
ars9 committed 2026-09-30 15:24:44 +03:00
1 parent a328ef5ea7
commit ff83b6c7da
40 files changed
+1457 -137

No files matched your search

+19
View File
@@ -2,6 +2,25 @@
All notable changes to this project will be documented in this file. All notable changes to this project will be documented in this file.
## 1.16.0 - 2026-09-30
Changes since 1.15.0:
### Added
- Scenarios and snippets are now versioned, starting at version 1. A scenario's version goes up when its name, description, default environment, timeout or steps change; a snippet's when its alias, title, description or code changes. Saving without changes does not create a new version. Credential assignments and scenario files are not versioned.
- Each run records the scenario version it runs. The run modal has a version picker (latest by default), `POST /scenarios/:id/run` and the `run_scenario` MCP tool accept an optional `version`, and "Repeat run" reuses the run's version.
- `context.runSnippet("alias@N")` pins version N of a snippet; `runSnippet("alias")` keeps using the latest. The scenario page's "Used Snippets" section shows which snippets are pinned.
- Version numbers are shown on the scenario, snippet and run pages and in the scenario and run lists.
- Added `GET /scenarios/:id/versions[/:version]` and `GET /snippets/:id/versions[/:version]`, and the `list_scenario_versions`, `get_scenario_version`, `list_snippet_versions` and `get_snippet_version` MCP tools.
- Scenario and snippet exports accept `?version=N` (the `export_scenario` MCP tool takes `version`).
### Changed
- **Breaking:** scenario and snippet exports now include `version`, and imports require it. An import restores that exact version by id + version: an existing version is left untouched, and a new one is stored under its number and becomes the latest when it is higher than the current latest. Export files from earlier releases need a `version` field added before they can be imported.
- Scenario exports now include scenario and step timeouts.
- Runs keep their own copy of the steps they were created with. Editing or deleting a step no longer changes past runs, and deleting a step no longer deletes its results from past runs. Existing run steps are backfilled from the current steps on startup.
## 1.15.0 - 2026-09-30 ## 1.15.0 - 2026-09-30
Changes since 1.14.0: Changes since 1.14.0:
+13 -2
View File
@@ -12,8 +12,11 @@ import type {
ScenarioRunDetail, ScenarioRunDetail,
ScenarioRunStep, ScenarioRunStep,
ScenarioStep, ScenarioStep,
ScenarioVersion,
Snippet, Snippet,
SnippetVersion,
TraceMode, TraceMode,
UsedSnippet,
} from './types'; } from './types';
import { emitApiErrorToast } from '../lib/toast-events'; import { emitApiErrorToast } from '../lib/toast-events';
@@ -122,6 +125,9 @@ export const snippets = {
remove(id: string): Promise<void> { remove(id: string): Promise<void> {
return request(`/snippets/${id}`, { method: 'DELETE' }); return request(`/snippets/${id}`, { method: 'DELETE' });
}, },
versions(id: string): Promise<SnippetVersion[]> {
return request(`/snippets/${id}/versions`);
},
exportSnippet(id: string): Promise<unknown> { exportSnippet(id: string): Promise<unknown> {
return request(`/snippets/${id}/export`); return request(`/snippets/${id}/export`);
}, },
@@ -229,12 +235,17 @@ export const scenarios = {
environmentId: string, environmentId: string,
saveSession?: boolean, saveSession?: boolean,
traceMode?: TraceMode, traceMode?: TraceMode,
/** Scenario version to run; omit for the latest. */
version?: number,
): Promise<ScenarioRun> { ): Promise<ScenarioRun> {
return request(`/scenarios/${id}/run`, { return request(`/scenarios/${id}/run`, {
method: 'POST', method: 'POST',
body: JSON.stringify({ environmentId, saveSession, traceMode }), body: JSON.stringify({ environmentId, saveSession, traceMode, version }),
}); });
}, },
versions(id: string): Promise<ScenarioVersion[]> {
return request(`/scenarios/${id}/versions`);
},
runDefaults(): Promise<RunDefaults> { runDefaults(): Promise<RunDefaults> {
return request('/scenarios/run-defaults'); return request('/scenarios/run-defaults');
}, },
@@ -274,7 +285,7 @@ export const scenarios = {
exportE2eTestUrl(id: string): string { exportE2eTestUrl(id: string): string {
return `${BASE_URL}/scenarios/${id}/export-e2e`; return `${BASE_URL}/scenarios/${id}/export-e2e`;
}, },
usedSnippets(id: string): Promise<Snippet[]> { usedSnippets(id: string): Promise<UsedSnippet[]> {
return request(`/scenarios/${id}/used-snippets`); return request(`/scenarios/${id}/used-snippets`);
}, },
}; };
+49 -2
View File
@@ -41,10 +41,29 @@ export interface Snippet {
title: string; title: string;
description: string | null; description: string | null;
code: string; code: string;
/** Latest version number. */
version: number;
createdAt: string; createdAt: string;
updatedAt: string; updatedAt: string;
} }
export interface SnippetVersion {
id: string;
snippetId: string;
version: number;
alias: string;
title: string;
description: string | null;
code: string;
createdAt: string;
}
/** A snippet referenced by a scenario's steps. */
export interface UsedSnippet extends Snippet {
/** Version pinned via runSnippet('alias@N'), or null for the latest. */
pinnedVersion: number | null;
}
// ── Sessions ────────────────────────────────────────────────────────────────── // ── Sessions ──────────────────────────────────────────────────────────────────
export type SessionStatus = 'open' | 'closed'; export type SessionStatus = 'open' | 'closed';
@@ -87,6 +106,8 @@ export interface Scenario {
description?: string; description?: string;
environmentId?: string | null; environmentId?: string | null;
timeoutSeconds?: number | null; timeoutSeconds?: number | null;
/** Latest version number. */
version: number;
environment?: Pick<Environment, 'id' | 'name'>; environment?: Pick<Environment, 'id' | 'name'>;
steps?: ScenarioStep[]; steps?: ScenarioStep[];
scenarioCredentials?: ScenarioCredential[]; scenarioCredentials?: ScenarioCredential[];
@@ -96,6 +117,26 @@ export interface Scenario {
updatedAt: string; updatedAt: string;
} }
export interface ScenarioStepSnapshot {
id: string | null;
order: number;
title: string | null;
execCode: string | null;
timeoutSeconds: number | null;
}
export interface ScenarioVersion {
id: string;
scenarioId: string;
version: number;
name: string;
description: string | null;
environmentId: string | null;
timeoutSeconds: number | null;
steps: ScenarioStepSnapshot[];
createdAt: string;
}
export type ScenarioRunStatus = 'pending' | 'in_progress' | 'pass' | 'fail'; export type ScenarioRunStatus = 'pending' | 'in_progress' | 'pass' | 'fail';
export type TraceMode = 'on' | 'retain-on-failure' | 'off'; export type TraceMode = 'on' | 'retain-on-failure' | 'off';
@@ -115,6 +156,8 @@ export interface ScenarioRun {
sessionId?: string | null; sessionId?: string | null;
saveSession: boolean; saveSession: boolean;
traceMode: TraceMode | null; traceMode: TraceMode | null;
/** Scenario version the run executes; null for runs created before versioning. */
scenarioVersion: number | null;
scenario?: Pick<Scenario, 'id' | 'name'>; scenario?: Pick<Scenario, 'id' | 'name'>;
environment?: Pick<Environment, 'id' | 'name'>; environment?: Pick<Environment, 'id' | 'name'>;
session?: { id: string; sessionName: string }; session?: { id: string; sessionName: string };
@@ -127,8 +170,12 @@ export interface ScenarioRun {
export interface ScenarioRunStep { export interface ScenarioRunStep {
id: string; id: string;
runId: string; runId: string;
scenarioStepId: string; /** Live step this run step came from; null once that step is deleted. */
scenarioStep: ScenarioStep; scenarioStepId: string | null;
// Step content as of the run's scenario version
title: string | null;
execCode: string | null;
timeoutSeconds: number | null;
status: RunStepStatus; status: RunStepStatus;
order: number; order: number;
description: string | null; description: string | null;
@@ -1,7 +1,7 @@
import { useTranslation } from 'react-i18next'; import { useTranslation } from 'react-i18next';
import { X, Play } from 'lucide-react'; import { X, Play } from 'lucide-react';
import { Modal, Button, Select } from '../../ui'; import { Modal, Button, Select } from '../../ui';
import type { Environment, TraceMode } from '../../api'; import type { Environment, ScenarioVersion, TraceMode } from '../../api';
const TRACE_MODES: TraceMode[] = ['on', 'retain-on-failure', 'off']; const TRACE_MODES: TraceMode[] = ['on', 'retain-on-failure', 'off'];
@@ -12,6 +12,11 @@ export interface RunScenarioModalProps {
onEnvSelect: (envId: string) => void; onEnvSelect: (envId: string) => void;
saveSessionFlag: boolean; saveSessionFlag: boolean;
onSaveSessionChange: (flag: boolean) => void; onSaveSessionChange: (flag: boolean) => void;
/** Scenario versions, newest first; empty while loading. */
versions: Pick<ScenarioVersion, 'version' | 'createdAt'>[];
/** Selected version, or null for the latest. */
selectedVersion: number | null;
onVersionChange: (version: number | null) => void;
traceMode: TraceMode; traceMode: TraceMode;
defaultTraceMode: TraceMode | null; defaultTraceMode: TraceMode | null;
onTraceModeChange: (mode: TraceMode) => void; onTraceModeChange: (mode: TraceMode) => void;
@@ -28,6 +33,9 @@ export function RunScenarioModal({
onEnvSelect, onEnvSelect,
saveSessionFlag, saveSessionFlag,
onSaveSessionChange, onSaveSessionChange,
versions,
selectedVersion,
onVersionChange,
traceMode, traceMode,
defaultTraceMode, defaultTraceMode,
onTraceModeChange, onTraceModeChange,
@@ -66,6 +74,25 @@ export function RunScenarioModal({
onChange={(e) => onEnvSelect(e.target.value)} onChange={(e) => onEnvSelect(e.target.value)}
options={environments.map((env) => ({ value: env.id, label: env.name }))} options={environments.map((env) => ({ value: env.id, label: env.name }))}
/> />
<div style={{ marginTop: '1rem' }}>
<Select
label={t('scenarios.run_modal_version_label')}
value={selectedVersion == null ? '' : String(selectedVersion)}
onChange={(e) => onVersionChange(e.target.value ? Number(e.target.value) : null)}
options={[
{
value: '',
label: versions[0]
? t('scenarios.run_modal_version_latest_n', { version: versions[0].version })
: t('scenarios.run_modal_version_latest'),
},
...versions.map((v) => ({
value: String(v.version),
label: `v${v.version} — ${new Date(v.createdAt).toLocaleString()}`,
})),
]}
/>
</div>
<label <label
style={{ style={{
display: 'flex', display: 'flex',
+10
View File
@@ -126,6 +126,7 @@
"run_started": "Scenario run started", "run_started": "Scenario run started",
"col_id": "ID", "col_id": "ID",
"col_name": "Name", "col_name": "Name",
"col_version": "Version",
"col_description": "Description", "col_description": "Description",
"col_last_run": "Last Run", "col_last_run": "Last Run",
"col_updated": "Updated", "col_updated": "Updated",
@@ -135,6 +136,7 @@
"action_delete": "Delete", "action_delete": "Delete",
"field_id": "ID", "field_id": "ID",
"field_name": "Name", "field_name": "Name",
"field_version": "Version",
"field_description": "Description", "field_description": "Description",
"field_steps": "Steps", "field_steps": "Steps",
"field_created": "Created", "field_created": "Created",
@@ -167,6 +169,8 @@
"form_name_required": "Name is required", "form_name_required": "Name is required",
"credentials_heading": "Credentials", "credentials_heading": "Credentials",
"used_snippets_heading": "Used Snippets", "used_snippets_heading": "Used Snippets",
"used_snippet_pinned": "v{{version}} (pinned)",
"used_snippet_latest": "Latest (v{{version}})",
"cred_empty": "No credentials assigned.", "cred_empty": "No credentials assigned.",
"cred_col_alias": "Alias", "cred_col_alias": "Alias",
"cred_col_name": "Credential", "cred_col_name": "Credential",
@@ -185,6 +189,9 @@
"run_modal_env_label": "Environment", "run_modal_env_label": "Environment",
"run_modal_no_env": "No environments found. Create an environment before running a scenario.", "run_modal_no_env": "No environments found. Create an environment before running a scenario.",
"run_modal_env_required": "Please select an environment", "run_modal_env_required": "Please select an environment",
"run_modal_version_label": "Version",
"run_modal_version_latest": "Latest",
"run_modal_version_latest_n": "Latest (v{{version}})",
"run_modal_trace_label": "Playwright trace", "run_modal_trace_label": "Playwright trace",
"trace_mode_on": "Always keep", "trace_mode_on": "Always keep",
"trace_mode_retain_on_failure": "Keep on failure", "trace_mode_retain_on_failure": "Keep on failure",
@@ -247,6 +254,7 @@
"col_scenario": "Scenario", "col_scenario": "Scenario",
"col_status": "Status", "col_status": "Status",
"col_steps": "Steps", "col_steps": "Steps",
"col_version": "Version",
"col_created": "Started", "col_created": "Started",
"field_id": "ID", "field_id": "ID",
"field_status": "Status", "field_status": "Status",
@@ -254,6 +262,7 @@
"field_created": "Started", "field_created": "Started",
"field_updated": "Updated", "field_updated": "Updated",
"field_trace": "Playwright trace", "field_trace": "Playwright trace",
"field_scenario_version": "Scenario version",
"steps_heading": "Step runs", "steps_heading": "Step runs",
"step_title": "Title", "step_title": "Title",
"logs_heading": "Logs", "logs_heading": "Logs",
@@ -303,6 +312,7 @@
"form_code_required": "Code is required", "form_code_required": "Code is required",
"field_id": "ID", "field_id": "ID",
"field_alias": "Alias", "field_alias": "Alias",
"field_version": "Version",
"field_title": "Title", "field_title": "Title",
"field_description": "Description", "field_description": "Description",
"field_created": "Created", "field_created": "Created",
+11
View File
@@ -96,6 +96,17 @@ export function AllRunsPage() {
sortable: true, sortable: true,
render: (r) => <Badge variant={STATUS_VARIANT[r.status]}>{STATUS_LABEL[r.status]}</Badge>, render: (r) => <Badge variant={STATUS_VARIANT[r.status]}>{STATUS_LABEL[r.status]}</Badge>,
}, },
{
key: 'scenarioVersion',
header: t('runs.col_version'),
width: 80,
render: (r) =>
r.scenarioVersion != null ? (
`v${r.scenarioVersion}`
) : (
<span className={styles.muted}>–</span>
),
},
{ {
key: 'createdAt', key: 'createdAt',
header: t('runs.col_created'), header: t('runs.col_created'),
+8 -1
View File
@@ -156,6 +156,7 @@ function RunDetail() {
run.environmentId, run.environmentId,
run.saveSession, run.saveSession,
run.traceMode ?? undefined, run.traceMode ?? undefined,
run.scenarioVersion ?? undefined,
); );
toast.success(t('scenarios.run_started')); toast.success(t('scenarios.run_started'));
navigate(`/scenarios/${id}/runs/${newRun.id}`); navigate(`/scenarios/${id}/runs/${newRun.id}`);
@@ -258,7 +259,7 @@ function RunDetail() {
key: 'title', key: 'title',
header: t('runs.step_title'), header: t('runs.step_title'),
width: 220, width: 220,
render: (s) => s.scenarioStep?.title ?? <span className={styles.muted}>–</span>, render: (s) => s.title ?? <span className={styles.muted}>–</span>,
}, },
{ {
key: 'status', key: 'status',
@@ -463,6 +464,12 @@ function RunDetail() {
{ term: t('runs.field_created'), detail: <Timestamp value={run.createdAt} /> }, { term: t('runs.field_created'), detail: <Timestamp value={run.createdAt} /> },
{ term: t('runs.field_updated'), detail: <Timestamp value={run.updatedAt} /> }, { term: t('runs.field_updated'), detail: <Timestamp value={run.updatedAt} /> },
]; ];
if (run.scenarioVersion != null) {
items.push({
term: t('runs.field_scenario_version'),
detail: <span>v{run.scenarioVersion}</span>,
});
}
if (run.traceMode) { if (run.traceMode) {
items.push({ items.push({
term: t('runs.field_trace'), term: t('runs.field_trace'),
+11
View File
@@ -161,6 +161,17 @@ export function RunsPage() {
sortable: true, sortable: true,
render: (r) => <Badge variant={STATUS_VARIANT[r.status]}>{STATUS_LABEL[r.status]}</Badge>, render: (r) => <Badge variant={STATUS_VARIANT[r.status]}>{STATUS_LABEL[r.status]}</Badge>,
}, },
{
key: 'scenarioVersion',
header: t('runs.col_version'),
width: 80,
render: (r) =>
r.scenarioVersion != null ? (
`v${r.scenarioVersion}`
) : (
<span className={styles.muted}>–</span>
),
},
{ {
key: 'createdAt', key: 'createdAt',
header: t('runs.col_created'), header: t('runs.col_created'),
@@ -29,8 +29,9 @@ import type {
Credential, Credential,
Environment, Environment,
FileMetadata, FileMetadata,
Snippet, ScenarioVersion,
TraceMode, TraceMode,
UsedSnippet,
} from '../../api'; } from '../../api';
import { import {
Breadcrumbs, Breadcrumbs,
@@ -78,6 +79,9 @@ export function ScenarioDetailPage() {
// null = use the server's configured default // null = use the server's configured default
const [traceModeOverride, setTraceModeOverride] = useState<TraceMode | null>(null); const [traceModeOverride, setTraceModeOverride] = useState<TraceMode | null>(null);
const runDefaults = useRunDefaults(); const runDefaults = useRunDefaults();
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 ?? 'on';
const [envs, setEnvs] = useState<Environment[]>([]); const [envs, setEnvs] = useState<Environment[]>([]);
const [selectedEnvId, setSelectedEnvId] = useState(''); const [selectedEnvId, setSelectedEnvId] = useState('');
@@ -102,7 +106,7 @@ export function ScenarioDetailPage() {
const [uploadExpiresAt, setUploadExpiresAt] = useState(''); const [uploadExpiresAt, setUploadExpiresAt] = useState('');
const [uploading, setUploading] = useState(false); const [uploading, setUploading] = useState(false);
const [usedSnippets, setUsedSnippets] = useState<Snippet[]>([]); const [usedSnippets, setUsedSnippets] = useState<UsedSnippet[]>([]);
const loadFiles = useCallback(async () => { const loadFiles = useCallback(async () => {
if (!id) return; if (!id) return;
@@ -175,6 +179,7 @@ export function ScenarioDetailPage() {
selectedEnvId, selectedEnvId,
saveSessionFlag, saveSessionFlag,
traceModeOverride ?? undefined, traceModeOverride ?? undefined,
runVersion ?? undefined,
); );
toast.success(t('scenarios.run_started')); toast.success(t('scenarios.run_started'));
navigate(`/scenarios/${id}/runs/${run.id}`); navigate(`/scenarios/${id}/runs/${run.id}`);
@@ -471,6 +476,14 @@ export function ScenarioDetailPage() {
size="sm" size="sm"
onClick={() => { onClick={() => {
setTraceModeOverride(null); setTraceModeOverride(null);
setRunVersion(null);
setRunVersions([]);
if (id) {
scenarios
.versions(id)
.then(setRunVersions)
.catch(() => undefined);
}
setRunModalOpen(true); setRunModalOpen(true);
}} }}
> >
@@ -521,6 +534,7 @@ export function ScenarioDetailPage() {
items={[ items={[
{ term: t('scenarios.field_id'), detail: <UuidBadge id={scenario.id} /> }, { term: t('scenarios.field_id'), detail: <UuidBadge id={scenario.id} /> },
{ term: t('scenarios.field_name'), detail: scenario.name }, { term: t('scenarios.field_name'), detail: scenario.name },
{ term: t('scenarios.field_version'), detail: `v${scenario.version}` },
...(scenario.environment ...(scenario.environment
? [ ? [
{ {
@@ -696,9 +710,9 @@ export function ScenarioDetailPage() {
<div className={styles.sectionToolbar}> <div className={styles.sectionToolbar}>
<h2 className={styles.sectionHeading}>{t('scenarios.used_snippets_heading')}</h2> <h2 className={styles.sectionHeading}>{t('scenarios.used_snippets_heading')}</h2>
</div> </div>
<Table<Snippet> <Table<UsedSnippet>
data={usedSnippets} data={usedSnippets}
rowKey={(s) => s.id} rowKey={(s) => `${s.id}@${s.pinnedVersion ?? 'latest'}`}
loading={false} loading={false}
emptyMessage="" emptyMessage=""
onRowClick={(s) => navigate(`/snippets/${s.id}`)} onRowClick={(s) => navigate(`/snippets/${s.id}`)}
@@ -714,7 +728,15 @@ export function ScenarioDetailPage() {
header: t('snippets.field_title'), header: t('snippets.field_title'),
render: (s) => s.title, render: (s) => s.title,
}, },
] satisfies TableColumn<Snippet>[] {
key: 'version',
header: t('snippets.field_version'),
render: (s) =>
s.pinnedVersion != null
? t('scenarios.used_snippet_pinned', { version: s.pinnedVersion })
: t('scenarios.used_snippet_latest', { version: s.version }),
},
] satisfies TableColumn<UsedSnippet>[]
} }
/> />
</div> </div>
@@ -850,6 +872,9 @@ export function ScenarioDetailPage() {
onEnvSelect={setSelectedEnvId} onEnvSelect={setSelectedEnvId}
saveSessionFlag={saveSessionFlag} saveSessionFlag={saveSessionFlag}
onSaveSessionChange={setSaveSessionFlag} onSaveSessionChange={setSaveSessionFlag}
versions={runVersions}
selectedVersion={runVersion}
onVersionChange={setRunVersion}
traceMode={traceMode} traceMode={traceMode}
defaultTraceMode={runDefaults?.traceMode ?? null} defaultTraceMode={runDefaults?.traceMode ?? null}
onTraceModeChange={setTraceModeOverride} onTraceModeChange={setTraceModeOverride}
+20 -1
View File
@@ -5,7 +5,7 @@ import { usePageTitle } from '../../hooks/usePageTitle';
import { Play, Plus, Trash2, Download, ClipboardList } from 'lucide-react'; import { Play, Plus, Trash2, Download, ClipboardList } from 'lucide-react';
import { parse as yamlParse } from 'yaml'; import { parse as yamlParse } from 'yaml';
import { environments, scenarios } from '../../api'; import { environments, scenarios } from '../../api';
import type { Environment, Scenario, TraceMode } from '../../api'; import type { Environment, Scenario, ScenarioVersion, TraceMode } from '../../api';
import { RunScenarioModal } from '../../components/modals'; import { RunScenarioModal } from '../../components/modals';
import { useRunDefaults } from '../../hooks/useRunDefaults'; import { useRunDefaults } from '../../hooks/useRunDefaults';
import { import {
@@ -53,6 +53,9 @@ export function ScenariosPage() {
// null = use the server's configured default // null = use the server's configured default
const [traceModeOverride, setTraceModeOverride] = useState<TraceMode | null>(null); const [traceModeOverride, setTraceModeOverride] = useState<TraceMode | null>(null);
const runDefaults = useRunDefaults(); const runDefaults = useRunDefaults();
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 ?? 'on';
const [envs, setEnvs] = useState<Environment[]>([]); const [envs, setEnvs] = useState<Environment[]>([]);
const [selectedEnvId, setSelectedEnvId] = useState(''); const [selectedEnvId, setSelectedEnvId] = useState('');
@@ -110,6 +113,12 @@ export function ScenariosPage() {
const openRunModal = (id: string) => { const openRunModal = (id: string) => {
setRunScenarioId(id); setRunScenarioId(id);
setTraceModeOverride(null); setTraceModeOverride(null);
setRunVersion(null);
setRunVersions([]);
scenarios
.versions(id)
.then(setRunVersions)
.catch(() => undefined);
const scenario = items.find((s) => s.id === id); const scenario = items.find((s) => s.id === id);
const preferred = scenario?.environmentId ?? null; const preferred = scenario?.environmentId ?? null;
const exists = preferred ? envs.some((e) => e.id === preferred) : false; const exists = preferred ? envs.some((e) => e.id === preferred) : false;
@@ -125,6 +134,7 @@ export function ScenariosPage() {
selectedEnvId, selectedEnvId,
saveSessionFlag, saveSessionFlag,
traceModeOverride ?? undefined, traceModeOverride ?? undefined,
runVersion ?? undefined,
); );
toast.success(t('scenarios.run_started')); toast.success(t('scenarios.run_started'));
navigate(`/scenarios/${runScenarioId}/runs/${run.id}`); navigate(`/scenarios/${runScenarioId}/runs/${run.id}`);
@@ -166,6 +176,12 @@ export function ScenariosPage() {
const columns: TableColumn<Scenario>[] = [ const columns: TableColumn<Scenario>[] = [
{ key: 'id', header: t('scenarios.col_id'), render: (s) => <UuidBadge id={s.id} />, width: 60 }, { key: 'id', header: t('scenarios.col_id'), render: (s) => <UuidBadge id={s.id} />, width: 60 },
{ key: 'name', header: t('scenarios.col_name'), render: (s) => s.name, sortable: true }, { key: 'name', header: t('scenarios.col_name'), render: (s) => s.name, sortable: true },
{
key: 'version',
header: t('scenarios.col_version'),
width: 80,
render: (s) => `v${s.version}`,
},
{ {
key: 'lastRunStatus', key: 'lastRunStatus',
header: t('scenarios.col_last_run'), header: t('scenarios.col_last_run'),
@@ -289,6 +305,9 @@ export function ScenariosPage() {
onEnvSelect={setSelectedEnvId} onEnvSelect={setSelectedEnvId}
saveSessionFlag={saveSessionFlag} saveSessionFlag={saveSessionFlag}
onSaveSessionChange={setSaveSessionFlag} onSaveSessionChange={setSaveSessionFlag}
versions={runVersions}
selectedVersion={runVersion}
onVersionChange={setRunVersion}
traceMode={traceMode} traceMode={traceMode}
defaultTraceMode={runDefaults?.traceMode ?? null} defaultTraceMode={runDefaults?.traceMode ?? null}
onTraceModeChange={setTraceModeOverride} onTraceModeChange={setTraceModeOverride}
@@ -107,6 +107,7 @@ export function SnippetDetailPage() {
{ term: t('snippets.field_id'), detail: <UuidBadge id={snippet.id} /> }, { term: t('snippets.field_id'), detail: <UuidBadge id={snippet.id} /> },
{ term: t('snippets.field_alias'), detail: snippet.alias }, { term: t('snippets.field_alias'), detail: snippet.alias },
{ term: t('snippets.field_title'), detail: snippet.title }, { term: t('snippets.field_title'), detail: snippet.title },
{ term: t('snippets.field_version'), detail: `v${snippet.version}` },
{ {
term: t('snippets.field_created'), term: t('snippets.field_created'),
detail: <Timestamp value={snippet.createdAt} />, detail: <Timestamp value={snippet.createdAt} />,
@@ -84,6 +84,7 @@ function SnippetCard({ snippet, onDelete }: { snippet: Snippet; onDelete: (id: s
> >
<p className={styles.muted}> <p className={styles.muted}>
{t('snippets.field_alias')}: <code className={styles.codeInline}>{snippet.alias}</code> {t('snippets.field_alias')}: <code className={styles.codeInline}>{snippet.alias}</code>
{' · '}v{snippet.version}
</p> </p>
{snippet.description && {snippet.description &&
(() => { (() => {
+17 -3
View File
@@ -44,11 +44,25 @@ The server currently registers the following tools.
| `update_scenario_step` | Update step fields | | `update_scenario_step` | Update step fields |
| `delete_scenario_step` | Delete step | | `delete_scenario_step` | Delete step |
| `list_scenario_runs` | List runs for a scenario | | `list_scenario_runs` | List runs for a scenario |
| `run_scenario` | Trigger run for scenario | | `list_scenario_versions` | List a scenario's versions, newest first |
| `get_scenario_version` | Get one scenario version with its steps |
| `run_scenario` | Trigger run for scenario; optional `version` (defaults to latest) and `traceMode` |
| `get_scenario_run` | Get run with step runs and logs | | `get_scenario_run` | Get run with step runs and logs |
| `wait_for_scenario_run` | Wait until run is `pass` or `fail` | | `wait_for_scenario_run` | Wait until run is `pass` or `fail` |
| `export_scenario` | Export scenario payload | | `export_scenario` | Export one scenario version (optional `version`, defaults to latest) |
| `import_scenario` | Import scenario payload | | `import_scenario` | Import one scenario version; `version` is required (see "Versioning" in `scenario.md`) |
## Snippets
| Tool | Description |
|---|---|
| `list_snippets` | List snippets (paginated) |
| `get_snippet` | Get one snippet (latest version) |
| `create_snippet` | Create snippet (`alias`, `title`, `code`) |
| `update_snippet` | Update snippet fields; bumps its version when content changes |
| `delete_snippet` | Delete snippet and all its versions |
| `list_snippet_versions` | List a snippet's versions, newest first |
| `get_snippet_version` | Get one snippet version |
## Scenario Files ## Scenario Files
+19 -1
View File
@@ -36,13 +36,31 @@ Available in scope:
- `context.dumpDom(selector?)`: simplified DOM snapshot - `context.dumpDom(selector?)`: simplified DOM snapshot
- `context.log(...args)`, `context.warn(...args)`, `context.error(...args)`: structured step logs - `context.log(...args)`, `context.warn(...args)`, `context.error(...args)`: structured step logs
- `context.assert(() => boolean, description)`: runs the arrow function and requires it to return `true`. Logs `description` (as a `log` entry on success, as an `error` entry on failure or exception), then throws to stop the step if the function returned anything other than `true` or threw - `context.assert(() => boolean, description)`: runs the arrow function and requires it to return `true`. Logs `description` (as a `log` entry on success, as an `error` entry on failure or exception), then throws to stop the step if the function returned anything other than `true` or threw
- `context.runSnippet(name, ...args)`: execute stored snippet code with the same context - `context.runSnippet(name, ...args)`: execute stored snippet code with the same context. `name` is the snippet alias for its latest version, or `alias@<version>` (e.g. `login@3`) to pin a specific version
- `context.getScenarioFiles(opts?)`: list files uploaded to the scenario (`limit`, `offset`) - `context.getScenarioFiles(opts?)`: list files uploaded to the scenario (`limit`, `offset`)
- `context.downloadFile(url, opts?)`: fetch `url` and save the result as a run artifact (requires a real scenario run — throws when invoked ad hoc, e.g. via the `exec_code` MCP tool). `opts` may include `method`, `headers`, `body`, `filename`. `url` also accepts a `data:` URI (`data:<mediaType>;base64,<data>` or `data:<mediaType>,<percent-encoded data>`) to save content generated in-script (e.g. a credential JWT) directly, without an actual network fetch. - `context.downloadFile(url, opts?)`: fetch `url` and save the result as a run artifact (requires a real scenario run — throws when invoked ad hoc, e.g. via the `exec_code` MCP tool). `opts` may include `method`, `headers`, `body`, `filename`. `url` also accepts a `data:` URI (`data:<mediaType>;base64,<data>` or `data:<mediaType>,<percent-encoded data>`) to save content generated in-script (e.g. a credential JWT) directly, without an actual network fetch.
- `console`: proxied to run logs (`log`, `warn`, `error`, etc.) - `console`: proxied to run logs (`log`, `warn`, `error`, etc.)
`validateCode` additionally receives `result` in scope, which is the value returned by `execCode`. `validateCode` additionally receives `result` in scope, which is the value returned by `execCode`.
## Versioning
Scenarios and snippets are versioned, starting at version 1.
- A scenario's version goes up when its content changes: name, description, default environment, timeout, or any step change (add, edit, delete, reorder). Credential assignments and uploaded files are not versioned. Saving without changes does not create a new version.
- A snippet's version goes up when its alias, title, description or code changes.
- The scenario and snippet pages always show the latest version. Older versions are available via `GET /scenarios/:id/versions[/:version]` and `GET /snippets/:id/versions[/:version]`.
- A run executes one scenario version, chosen in the run modal (latest by default) or via `version` in `POST /scenarios/:id/run`. The run keeps its own copy of that version's steps, so deleting or editing steps later doesn't change what the run shows. "Repeat run" reuses the run's version.
- Step code uses the latest version of a snippet by default. `context.runSnippet("alias@3")` pins version 3 instead. The version is looked up through the snippet's current alias. Pinned versions are listed under "Used Snippets" on the scenario page.
### Export / import
Exports hold exactly one version and always include its `version` number (the latest by default, or `?version=N`). Imports require `version`, and restore that exact version by id + version:
- If that version already exists, it is left untouched.
- Otherwise it is stored under that number, and becomes the latest if it is higher than the current latest version.
- Without an `id`, a new scenario or snippet is created at the given version.
## Playwright traces ## 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. 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.
+2 -2
View File
@@ -1,12 +1,12 @@
{ {
"name": "liqa", "name": "liqa",
"version": "1.15.0", "version": "1.16.0",
"lockfileVersion": 3, "lockfileVersion": 3,
"requires": true, "requires": true,
"packages": { "packages": {
"": { "": {
"name": "liqa", "name": "liqa",
"version": "1.15.0", "version": "1.16.0",
"workspaces": [ "workspaces": [
"server", "server",
"client" "client"
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "liqa", "name": "liqa",
"version": "1.15.0", "version": "1.16.0",
"private": true, "private": true,
"workspaces": [ "workspaces": [
"server", "server",
+4
View File
@@ -19,6 +19,8 @@ import { ScenarioRunLogEntity } from "./scenario/scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario/scenario-run-step.entity"; import { ScenarioRunStepEntity } from "./scenario/scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario/scenario-run.entity"; import { ScenarioRunEntity } from "./scenario/scenario-run.entity";
import { ScenarioStepEntity } from "./scenario/scenario-step.entity"; import { ScenarioStepEntity } from "./scenario/scenario-step.entity";
import { ScenarioVersionEntity } from "./scenario/scenario-version.entity";
import { SnippetVersionEntity } from "./snippet/snippet-version.entity";
import { ScenarioEntity } from "./scenario/scenario.entity"; import { ScenarioEntity } from "./scenario/scenario.entity";
import { ScenarioModule } from "./scenario/scenario.module"; import { ScenarioModule } from "./scenario/scenario.module";
import { SessionEntity } from "./session/session.entity"; import { SessionEntity } from "./session/session.entity";
@@ -44,11 +46,13 @@ import { SnippetModule } from "./snippet/snippet.module";
CredentialEntity, CredentialEntity,
ScenarioEntity, ScenarioEntity,
ScenarioStepEntity, ScenarioStepEntity,
ScenarioVersionEntity,
ScenarioRunEntity, ScenarioRunEntity,
ScenarioRunStepEntity, ScenarioRunStepEntity,
ScenarioRunLogEntity, ScenarioRunLogEntity,
ScenarioCredentialEntity, ScenarioCredentialEntity,
SnippetEntity, SnippetEntity,
SnippetVersionEntity,
FileEntity, FileEntity,
ScenarioFileEntity, ScenarioFileEntity,
ScenarioRunFileEntity, ScenarioRunFileEntity,
+14
View File
@@ -32,3 +32,17 @@ export function resolveUsedSnippetAliases(
} }
return used; return used;
} }
/**
* Splits a `runSnippet` reference into its alias and pinned version:
* `"login@3"` → `{ alias: "login", version: 3 }`, `"login"` → `{ alias: "login", version: null }`.
*/
export function parseSnippetRef(ref: string): {
alias: string;
version: number | null;
} {
const match = /^(.+)@(\d+)$/.exec(ref);
return match
? { alias: match[1], version: Number(match[2]) }
: { alias: ref, version: null };
}
+130 -7
View File
@@ -946,15 +946,24 @@ export class McpService {
.describe( .describe(
"Playwright trace recording: on (keep every trace), retain-on-failure, or off. Defaults to the server's PLAYWRIGHT_TRACE_MODE", "Playwright trace recording: on (keep every trace), retain-on-failure, or off. Defaults to the server's PLAYWRIGHT_TRACE_MODE",
), ),
version: z
.number()
.int()
.min(1)
.optional()
.describe(
"Scenario version to run (see list_scenario_versions). Defaults to the latest",
),
}, },
}, },
async ({ id, environmentId, saveSession, traceMode }) => { async ({ id, environmentId, saveSession, traceMode, version }) => {
try { try {
const run = await this.scenarioService.createRun( const run = await this.scenarioService.createRun(
id, id,
environmentId, environmentId,
saveSession, saveSession,
traceMode, traceMode,
version,
); );
return { return {
content: [{ type: "text" as const, text: JSON.stringify(run) }], content: [{ type: "text" as const, text: JSON.stringify(run) }],
@@ -1155,19 +1164,74 @@ export class McpService {
); );
server.registerTool( server.registerTool(
"export_scenario", "list_scenario_versions",
{ {
description: description:
"Export a scenario as a portable JSON payload (name + steps)", "List a scenario's versions, newest first. Each version holds the scenario content and steps as of that version",
inputSchema: { inputSchema: {
id: z.uuid().describe("Scenario ID to export"), id: z.uuid().describe("Scenario ID"),
}, },
}, },
async ({ id }) => { async ({ id }) => {
try {
const versions = await this.scenarioService.listVersions(id);
return {
content: [{ type: "text" as const, text: JSON.stringify(versions) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"get_scenario_version",
{
description: "Get one version of a scenario, with its steps",
inputSchema: {
id: z.uuid().describe("Scenario ID"),
version: z.number().int().min(1).describe("Scenario version"),
},
},
async ({ id, version }) => {
try {
const row = await this.scenarioService.findVersion(id, version);
return {
content: [{ type: "text" as const, text: JSON.stringify(row) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"export_scenario",
{
description:
"Export one version of a scenario as a portable JSON payload (version, name + steps)",
inputSchema: {
id: z.uuid().describe("Scenario ID to export"),
version: z
.number()
.int()
.min(1)
.optional()
.describe("Scenario version to export. Defaults to the latest"),
},
},
async ({ id, version }) => {
try { try {
const exported = await this.scenarioService.exportScenario(id, { const exported = await this.scenarioService.exportScenario(id, {
includeEnvironment: false, includeEnvironment: false,
credentialIds: [], credentialIds: [],
version,
}); });
return { return {
content: [ content: [
@@ -1187,8 +1251,17 @@ export class McpService {
"import_scenario", "import_scenario",
{ {
description: description:
"Import a scenario from an export payload, creating a new scenario with all its steps", "Import one scenario version from an export payload. Upserts by id + version: an existing version is left untouched; a new one is stored under its number and becomes the latest when higher than the current latest. Without an id a new scenario is created",
inputSchema: { inputSchema: {
id: z
.uuid()
.optional()
.describe("Scenario ID to import into (from the export)"),
version: z
.number()
.int()
.min(1)
.describe("Scenario version the payload holds (from the export)"),
name: z.string().describe("Scenario name"), name: z.string().describe("Scenario name"),
description: z description: z
.string() .string()
@@ -1210,10 +1283,12 @@ export class McpService {
.describe("Ordered list of steps"), .describe("Ordered list of steps"),
}, },
}, },
async ({ name, description, steps }) => { async ({ id, version, name, description, steps }) => {
try { try {
const scenario = await this.scenarioService.importScenario({ const scenario = await this.scenarioService.importScenario({
kind: "scenario", kind: "scenario",
id,
version,
name, name,
description, description,
steps: steps as { title: string | null; execCode: string | null }[], steps: steps as { title: string | null; execCode: string | null }[],
@@ -1595,7 +1670,7 @@ export class McpService {
alias: z alias: z
.string() .string()
.describe( .describe(
"Unique identifier used to invoke the snippet via context.runSnippet(alias, ...args)", "Unique identifier used to invoke the snippet via context.runSnippet(alias, ...args). Use 'alias@<version>' to pin a specific version instead of the latest",
), ),
title: z.string().describe("Human-readable title"), title: z.string().describe("Human-readable title"),
description: z description: z
@@ -1664,6 +1739,54 @@ export class McpService {
}, },
); );
server.registerTool(
"list_snippet_versions",
{
description:
"List a snippet's versions, newest first. Step code pins a version with context.runSnippet('alias@<version>')",
inputSchema: {
id: z.uuid().describe("Snippet ID"),
},
},
async ({ id }) => {
try {
const versions = await this.snippetService.listVersions(id);
return {
content: [{ type: "text" as const, text: JSON.stringify(versions) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool(
"get_snippet_version",
{
description: "Get one version of a snippet",
inputSchema: {
id: z.uuid().describe("Snippet ID"),
version: z.number().int().min(1).describe("Snippet version"),
},
},
async ({ id, version }) => {
try {
const row = await this.snippetService.findVersion(id, version);
return {
content: [{ type: "text" as const, text: JSON.stringify(row) }],
};
} catch (err) {
return {
isError: true,
content: [{ type: "text" as const, text: (err as Error).message }],
};
}
},
);
server.registerTool( server.registerTool(
"delete_snippet", "delete_snippet",
{ {
@@ -1,9 +1,11 @@
import { import {
IsBoolean, IsBoolean,
IsEnum, IsEnum,
IsInt,
IsNotEmpty, IsNotEmpty,
IsOptional, IsOptional,
IsUUID, IsUUID,
Min,
} from "class-validator"; } from "class-validator";
import { TraceMode } from "../../config/app.config"; import { TraceMode } from "../../config/app.config";
@@ -19,4 +21,10 @@ export class CreateScenarioRunDto {
@IsEnum(TraceMode) @IsEnum(TraceMode)
@IsOptional() @IsOptional()
traceMode?: TraceMode; traceMode?: TraceMode;
/** Scenario version to run; defaults to the latest. */
@IsInt()
@Min(1)
@IsOptional()
version?: number;
} }
@@ -3,11 +3,13 @@ import { Type } from "class-transformer";
import { import {
IsArray, IsArray,
IsIn, IsIn,
IsInt,
IsNotEmpty, IsNotEmpty,
IsObject, IsObject,
IsOptional, IsOptional,
IsString, IsString,
IsUUID, IsUUID,
Min,
ValidateNested, ValidateNested,
} from "class-validator"; } from "class-validator";
import { EnvironmentData } from "../../environment/environment.entity"; import { EnvironmentData } from "../../environment/environment.entity";
@@ -24,6 +26,12 @@ export class ScenarioStepExportDto {
@IsString() @IsString()
@IsNotEmpty() @IsNotEmpty()
execCode: string | null; execCode: string | null;
@ApiPropertyOptional()
@IsOptional()
@IsInt()
@Min(1)
timeoutSeconds?: number | null;
} }
export class CredentialExportDto { export class CredentialExportDto {
@@ -117,6 +125,17 @@ export class ScenarioExportDto {
@IsUUID() @IsUUID()
environmentId?: string; environmentId?: string;
@ApiProperty({ description: "Scenario version this export holds" })
@IsInt()
@Min(1)
version: number;
@ApiPropertyOptional()
@IsOptional()
@IsInt()
@Min(1)
timeoutSeconds?: number;
@ApiPropertyOptional({ type: [ScenarioCredentialMappingDto] }) @ApiPropertyOptional({ type: [ScenarioCredentialMappingDto] })
@IsOptional() @IsOptional()
@IsArray() @IsArray()
@@ -32,12 +32,24 @@ export class ScenarioRunStepEntity {
@JoinColumn({ name: "runId" }) @JoinColumn({ name: "runId" })
run: ScenarioRunEntity; run: ScenarioRunEntity;
@Column("text") /** Live step this run step was created from; null once that step is deleted. */
scenarioStepId: string; @Column("text", { nullable: true })
scenarioStepId: string | null;
@ManyToOne(() => ScenarioStepEntity, { onDelete: "CASCADE" }) @ManyToOne(() => ScenarioStepEntity, { onDelete: "SET NULL", nullable: true })
@JoinColumn({ name: "scenarioStepId" }) @JoinColumn({ name: "scenarioStepId" })
scenarioStep: ScenarioStepEntity; scenarioStep: ScenarioStepEntity | null;
// Step content copied from the run's scenario version, so the run executes
// (and keeps showing) exactly what it was created with.
@Column({ type: "text", nullable: true })
title: string | null;
@Column({ type: "text", nullable: true })
execCode: string | null;
@Column({ type: "int", nullable: true })
timeoutSeconds: number | null;
@Column({ type: "text", default: "waiting" }) @Column({ type: "text", default: "waiting" })
status: RunStepStatus; status: RunStepStatus;
@@ -42,6 +42,10 @@ export class ScenarioRunEntity {
@JoinColumn({ name: "sessionId" }) @JoinColumn({ name: "sessionId" })
session: SessionEntity | null; session: SessionEntity | null;
/** Scenario version this run executes; null for runs created before versioning. */
@Column({ type: "int", nullable: true, default: null })
scenarioVersion: number | null;
@Column({ type: "text", default: "pending" }) @Column({ type: "text", default: "pending" })
status: RunStatus; status: RunStatus;
@@ -27,7 +27,6 @@ import { SnippetService } from "../snippet/snippet.service";
import { ScenarioRunLogEntity } from "./scenario-run-log.entity"; import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario-run-step.entity"; import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario-run.entity"; import { ScenarioRunEntity } from "./scenario-run.entity";
import { ScenarioStepEntity } from "./scenario-step.entity";
import { ScenarioService } from "./scenario.service"; import { ScenarioService } from "./scenario.service";
interface BrowserHandle { interface BrowserHandle {
@@ -215,10 +214,19 @@ export class ScenarioSchedulerService implements OnModuleInit {
.then((env) => env?.data ?? {}) .then((env) => env?.data ?? {})
.catch(() => ({}) as EnvironmentData); .catch(() => ({}) as EnvironmentData);
this.runEnvironments.set(run.id, environmentData); this.runEnvironments.set(run.id, environmentData);
const scenario = await this.scenarioService // Legacy runs (no scenarioVersion) fall back to the live scenario
.findOne(run.scenarioId) const versioned =
.catch(() => null); run.scenarioVersion != null
this.runScenarioTimeouts.set(run.id, scenario?.timeoutSeconds ?? null); ? await this.scenarioService
.findVersion(run.scenarioId, run.scenarioVersion)
.catch(() => null)
: await this.scenarioService
.findOne(run.scenarioId)
.catch(() => null);
this.runScenarioTimeouts.set(
run.id,
versioned?.timeoutSeconds ?? null,
);
this.runScenarioIds.set(run.id, run.scenarioId); this.runScenarioIds.set(run.id, run.scenarioId);
this.runTraceModes.set( this.runTraceModes.set(
run.id, run.id,
@@ -263,7 +271,6 @@ export class ScenarioSchedulerService implements OnModuleInit {
try { try {
let stepRun = await this.runStepRepo.findOne({ let stepRun = await this.runStepRepo.findOne({
where: { runId, status: "pending" }, where: { runId, status: "pending" },
relations: ["scenarioStep"],
order: { order: "ASC" }, order: { order: "ASC" },
}); });
while (stepRun) { while (stepRun) {
@@ -280,7 +287,6 @@ export class ScenarioSchedulerService implements OnModuleInit {
await this.executeStepRun(stepRun); await this.executeStepRun(stepRun);
stepRun = await this.runStepRepo.findOne({ stepRun = await this.runStepRepo.findOne({
where: { runId, status: "pending" }, where: { runId, status: "pending" },
relations: ["scenarioStep"],
order: { order: "ASC" }, order: { order: "ASC" },
}); });
} }
@@ -365,12 +371,13 @@ export class ScenarioSchedulerService implements OnModuleInit {
} }
private async executeStepRun(stepRun: ScenarioRunStepEntity): Promise<void> { private async executeStepRun(stepRun: ScenarioRunStepEntity): Promise<void> {
const step = stepRun.scenarioStep as ScenarioStepEntity; // Run steps carry a copy of the step from the run's scenario version
const step = stepRun;
stepRun.status = "in_progress"; stepRun.status = "in_progress";
await this.runStepRepo.save(stepRun); await this.runStepRepo.save(stepRun);
this.logger.log( this.logger.log(
`StepRun #${stepRun.id} (run #${stepRun.runId}, step #${step.id} order=${step.order}) → in_progress`, `StepRun #${stepRun.id} (run #${stepRun.runId}, step #${step.scenarioStepId ?? "deleted"} order=${step.order}) → in_progress`,
); );
this.persistLog( this.persistLog(
stepRun.runId, stepRun.runId,
@@ -549,7 +556,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
stepRun.runId, stepRun.runId,
stepRun.id, stepRun.id,
"log", "log",
`Step ${(stepRun.scenarioStep as ScenarioStepEntity | undefined)?.order ?? "?"} passed`, `Step ${stepRun.order} passed`,
); );
// Find the next waiting step in this run (next by order) // Find the next waiting step in this run (next by order)
@@ -591,7 +598,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
stepRun.runId, stepRun.runId,
stepRun.id, stepRun.id,
"error", "error",
`Step ${(stepRun.scenarioStep as ScenarioStepEntity | undefined)?.order ?? "?"} failed: ${description}`, `Step ${stepRun.order} failed: ${description}`,
); );
await this.dumpPageOnFailure(stepRun); await this.dumpPageOnFailure(stepRun);
@@ -624,8 +631,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
const handle = this.runBrowsers.get(stepRun.runId); const handle = this.runBrowsers.get(stepRun.runId);
if (!handle) return; // no browser was ever opened for this run (e.g. setup error) if (!handle) return; // no browser was ever opened for this run (e.g. setup error)
const step = stepRun.scenarioStep as ScenarioStepEntity | undefined; const namePrefix = `step-${stepRun.order}-failure`;
const namePrefix = `step-${step?.order ?? stepRun.id}-failure`;
try { try {
const screenshot = await handle.page.screenshot({ fullPage: true }); const screenshot = await handle.page.screenshot({ fullPage: true });
@@ -659,7 +665,7 @@ export class ScenarioSchedulerService implements OnModuleInit {
stepRun.runId, stepRun.runId,
stepRun.id, stepRun.id,
"log", "log",
`Step ${step?.order ?? "?"} failed: page dump uploaded to run files`, `Step ${stepRun.order} failed: page dump uploaded to run files`,
); );
} }
} }
@@ -0,0 +1,59 @@
import {
Column,
CreateDateColumn,
Entity,
JoinColumn,
ManyToOne,
PrimaryGeneratedColumn,
Unique,
} from "typeorm";
import { ScenarioEntity } from "./scenario.entity";
/** A step as it was at a given scenario version. */
export interface ScenarioStepSnapshot {
/** Id of the live step this snapshot was taken from (may no longer exist). */
id: string | null;
order: number;
title: string | null;
execCode: string | null;
timeoutSeconds: number | null;
}
/**
* Immutable snapshot of a scenario's content at one version. The `scenarios`
* and `scenario_steps` tables always hold the latest version.
*/
@Entity("scenario_versions")
@Unique(["scenarioId", "version"])
export class ScenarioVersionEntity {
@PrimaryGeneratedColumn("uuid")
id: string;
@Column("text")
scenarioId: string;
@ManyToOne(() => ScenarioEntity, { onDelete: "CASCADE" })
@JoinColumn({ name: "scenarioId" })
scenario: ScenarioEntity;
@Column({ type: "int" })
version: number;
@Column()
name: string;
@Column("text", { nullable: true })
description: string | null;
@Column({ type: "text", nullable: true })
environmentId: string | null;
@Column({ type: "int", nullable: true })
timeoutSeconds: number | null;
@Column("simple-json")
steps: ScenarioStepSnapshot[];
@CreateDateColumn()
createdAt: Date;
}
@@ -5,6 +5,7 @@ import {
Get, Get,
HttpCode, HttpCode,
Param, Param,
ParseIntPipe,
ParseUUIDPipe, ParseUUIDPipe,
Patch, Patch,
Post, Post,
@@ -105,6 +106,25 @@ export class ScenarioController {
return this.scenarioService.remove(id); return this.scenarioService.remove(id);
} }
@Get(":id/versions")
@ApiOperation({ summary: "List a scenario's versions, newest first" })
@ApiResponse({ status: 200 })
@ApiResponse({ status: 404, description: "Scenario not found" })
listVersions(@Param("id", ParseUUIDPipe) id: string) {
return this.scenarioService.listVersions(id);
}
@Get(":id/versions/:version")
@ApiOperation({ summary: "Get one version of a scenario, with its steps" })
@ApiResponse({ status: 200 })
@ApiResponse({ status: 404, description: "Scenario or version not found" })
findVersion(
@Param("id", ParseUUIDPipe) id: string,
@Param("version", ParseIntPipe) version: number,
) {
return this.scenarioService.findVersion(id, version);
}
@Get(":id/export") @Get(":id/export")
@ApiOperation({ summary: "Export a scenario as portable YAML" }) @ApiOperation({ summary: "Export a scenario as portable YAML" })
@ApiResponse({ status: 200 }) @ApiResponse({ status: 200 })
@@ -113,6 +133,8 @@ export class ScenarioController {
@Param("id", ParseUUIDPipe) id: string, @Param("id", ParseUUIDPipe) id: string,
@Query("includeEnvironment") includeEnvironment: string, @Query("includeEnvironment") includeEnvironment: string,
@Query("credentialIds") credentialIds: string | string[] | undefined, @Query("credentialIds") credentialIds: string | string[] | undefined,
@Query("version", new ParseIntPipe({ optional: true }))
version: number | undefined,
@Res({ passthrough: true }) res: Response, @Res({ passthrough: true }) res: Response,
) { ) {
const credIds: string[] = credentialIds const credIds: string[] = credentialIds
@@ -123,6 +145,7 @@ export class ScenarioController {
const entities = await this.scenarioService.exportScenario(id, { const entities = await this.scenarioService.exportScenario(id, {
includeEnvironment: includeEnvironment === "true", includeEnvironment: includeEnvironment === "true",
credentialIds: credIds, credentialIds: credIds,
version,
}); });
res.setHeader("Content-Type", "application/yaml; charset=utf-8"); res.setHeader("Content-Type", "application/yaml; charset=utf-8");
// Serialize as YAML stream: each entity separated by a comment header // Serialize as YAML stream: each entity separated by a comment header
@@ -284,6 +307,7 @@ export class ScenarioController {
dto.environmentId, dto.environmentId,
dto.saveSession, dto.saveSession,
dto.traceMode, dto.traceMode,
dto.version,
); );
} }
+4
View File
@@ -29,6 +29,10 @@ export class ScenarioEntity {
@Column({ type: "int", nullable: true }) @Column({ type: "int", nullable: true })
timeoutSeconds: number | null; timeoutSeconds: number | null;
/** Latest version number; incremented whenever the scenario content changes. */
@Column({ type: "int", default: 1 })
version: number;
@ManyToOne(() => EnvironmentEntity, { nullable: true, onDelete: "SET NULL", eager: false }) @ManyToOne(() => EnvironmentEntity, { nullable: true, onDelete: "SET NULL", eager: false })
@JoinColumn({ name: "environmentId" }) @JoinColumn({ name: "environmentId" })
environment: EnvironmentEntity | null; environment: EnvironmentEntity | null;
+2
View File
@@ -14,6 +14,7 @@ import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario-run-step.entity"; import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario-run.entity"; import { ScenarioRunEntity } from "./scenario-run.entity";
import { ScenarioSchedulerService } from "./scenario-scheduler.service"; import { ScenarioSchedulerService } from "./scenario-scheduler.service";
import { ScenarioVersionEntity } from "./scenario-version.entity";
import { ScenarioStepEntity } from "./scenario-step.entity"; import { ScenarioStepEntity } from "./scenario-step.entity";
import { ScenarioController } from "./scenario.controller"; import { ScenarioController } from "./scenario.controller";
import { ScenarioEntity } from "./scenario.entity"; import { ScenarioEntity } from "./scenario.entity";
@@ -25,6 +26,7 @@ import { E2eExportService } from "./e2e-export.service";
TypeOrmModule.forFeature([ TypeOrmModule.forFeature([
ScenarioEntity, ScenarioEntity,
ScenarioStepEntity, ScenarioStepEntity,
ScenarioVersionEntity,
ScenarioRunEntity, ScenarioRunEntity,
ScenarioRunStepEntity, ScenarioRunStepEntity,
ScenarioRunLogEntity, ScenarioRunLogEntity,
+257 -54
View File
@@ -3,6 +3,7 @@ import {
ConflictException, ConflictException,
Injectable, Injectable,
NotFoundException, NotFoundException,
OnModuleInit,
} from "@nestjs/common"; } from "@nestjs/common";
import { ConfigService } from "@nestjs/config"; import { ConfigService } from "@nestjs/config";
import { InjectRepository } from "@nestjs/typeorm"; import { InjectRepository } from "@nestjs/typeorm";
@@ -13,7 +14,10 @@ import {
PaginatedResult, PaginatedResult,
PaginationQueryDto, PaginationQueryDto,
} from "../common/dto/pagination.dto"; } from "../common/dto/pagination.dto";
import { resolveUsedSnippetAliases } from "../common/snippet-usage"; import {
parseSnippetRef,
resolveUsedSnippetAliases,
} from "../common/snippet-usage";
import type { AppConfig, TraceMode } from "../config/app.config"; import type { AppConfig, TraceMode } from "../config/app.config";
import { CredentialEntity } from "../credential/credential.entity"; import { CredentialEntity } from "../credential/credential.entity";
import { EnvironmentEntity } from "../environment/environment.entity"; import { EnvironmentEntity } from "../environment/environment.entity";
@@ -39,6 +43,10 @@ import { ScenarioRunLogEntity } from "./scenario-run-log.entity";
import { ScenarioRunStepEntity } from "./scenario-run-step.entity"; import { ScenarioRunStepEntity } from "./scenario-run-step.entity";
import { ScenarioRunEntity } from "./scenario-run.entity"; import { ScenarioRunEntity } from "./scenario-run.entity";
import { ScenarioStepEntity } from "./scenario-step.entity"; import { ScenarioStepEntity } from "./scenario-step.entity";
import {
ScenarioStepSnapshot,
ScenarioVersionEntity,
} from "./scenario-version.entity";
import { ScenarioEntity } from "./scenario.entity"; import { ScenarioEntity } from "./scenario.entity";
import { Response } from "express"; import { Response } from "express";
import type { File as MulterFile } from "multer"; import type { File as MulterFile } from "multer";
@@ -46,13 +54,49 @@ import type { File as MulterFile } from "multer";
export { PaginatedResult } from "../common/dto/pagination.dto"; export { PaginatedResult } from "../common/dto/pagination.dto";
export type ScenarioOrderBy = "id" | "name" | "createdAt" | "updatedAt"; export type ScenarioOrderBy = "id" | "name" | "createdAt" | "updatedAt";
/** The versioned content of a scenario. */
type ScenarioContent = Pick<
ScenarioVersionEntity,
"name" | "description" | "environmentId" | "timeoutSeconds" | "steps"
>;
function contentKey(c: ScenarioContent): string {
return JSON.stringify([
c.name,
c.description ?? null,
c.environmentId ?? null,
c.timeoutSeconds ?? null,
// Step ids are not content: re-created steps with equal content are equal
c.steps.map((s) => [s.order, s.title, s.execCode, s.timeoutSeconds]),
]);
}
function stepsSnapshot(steps: ScenarioStepEntity[]): ScenarioStepSnapshot[] {
return [...steps]
.sort((a, b) => a.order - b.order)
.map((s) => ({
id: s.id,
order: s.order,
title: s.title,
execCode: s.execCode,
timeoutSeconds: s.timeoutSeconds,
}));
}
export type UsedSnippet = SnippetEntity & {
/** Version pinned via `runSnippet("alias@N")`, or null for the latest. */
pinnedVersion: number | null;
};
@Injectable() @Injectable()
export class ScenarioService { export class ScenarioService implements OnModuleInit {
constructor( constructor(
@InjectRepository(ScenarioEntity) @InjectRepository(ScenarioEntity)
private readonly scenarioRepo: Repository<ScenarioEntity>, private readonly scenarioRepo: Repository<ScenarioEntity>,
@InjectRepository(ScenarioStepEntity) @InjectRepository(ScenarioStepEntity)
private readonly stepRepo: Repository<ScenarioStepEntity>, private readonly stepRepo: Repository<ScenarioStepEntity>,
@InjectRepository(ScenarioVersionEntity)
private readonly versionRepo: Repository<ScenarioVersionEntity>,
@InjectRepository(ScenarioRunEntity) @InjectRepository(ScenarioRunEntity)
private readonly runRepo: Repository<ScenarioRunEntity>, private readonly runRepo: Repository<ScenarioRunEntity>,
@InjectRepository(ScenarioRunStepEntity) @InjectRepository(ScenarioRunStepEntity)
@@ -74,10 +118,93 @@ export class ScenarioService {
private readonly configService: ConfigService<AppConfig, true>, private readonly configService: ConfigService<AppConfig, true>,
) {} ) {}
async onModuleInit(): Promise<void> {
await this.backfillVersions();
await this.backfillRunStepSnapshots();
}
/** Records the current content of scenarios that have no row for their current version yet. */
private async backfillVersions(): Promise<void> {
const scenarios = await this.scenarioRepo.find({ select: { id: true } });
for (const { id } of scenarios) await this.commitVersion(id);
}
/**
* Run steps created before versioning point at the live step instead of
* holding a copy of it; copy the live step content into them.
*/
private async backfillRunStepSnapshots(): Promise<void> {
await this.runStepRepo.query(`
UPDATE scenario_run_steps SET
title = (SELECT title FROM scenario_steps WHERE id = scenarioStepId),
execCode = (SELECT execCode FROM scenario_steps WHERE id = scenarioStepId),
timeoutSeconds = (SELECT timeoutSeconds FROM scenario_steps WHERE id = scenarioStepId)
WHERE title IS NULL AND execCode IS NULL AND timeoutSeconds IS NULL
AND scenarioStepId IS NOT NULL
AND runId IN (SELECT id FROM scenario_runs WHERE scenarioVersion IS NULL)
`);
}
// ── Versions ──────────────────────────────────────────────────────────────
/**
* Snapshots the scenario's current content. The first snapshot is stored as
* the scenario's current version; later ones bump the version, unless the
* content is unchanged since the latest snapshot.
*/
private async commitVersion(scenarioId: string): Promise<void> {
const scenario = await this.findOne(scenarioId);
const content: ScenarioContent = {
name: scenario.name,
description: scenario.description,
environmentId: scenario.environmentId,
timeoutSeconds: scenario.timeoutSeconds,
steps: stepsSnapshot(scenario.steps),
};
const latest = await this.versionRepo.findOneBy({
scenarioId,
version: scenario.version,
});
if (latest && contentKey(latest) === contentKey(content)) return;
const version = latest ? scenario.version + 1 : scenario.version;
if (version !== scenario.version) {
await this.scenarioRepo.update(scenarioId, { version });
}
await this.versionRepo.save(
this.versionRepo.create({ scenarioId, version, ...content }),
);
}
async listVersions(scenarioId: string): Promise<ScenarioVersionEntity[]> {
await this.findOne(scenarioId); // 404 guard
return this.versionRepo.find({
where: { scenarioId },
order: { version: "DESC" },
});
}
async findVersion(
scenarioId: string,
version: number,
): Promise<ScenarioVersionEntity> {
await this.findOne(scenarioId); // 404 guard
const row = await this.versionRepo.findOneBy({ scenarioId, version });
if (!row) {
throw new NotFoundException(
`Scenario ${scenarioId} has no version ${version}`,
);
}
return row;
}
// ── Scenarios ───────────────────────────────────────────────────────────── // ── Scenarios ─────────────────────────────────────────────────────────────
create(dto: CreateScenarioDto): Promise<ScenarioEntity> { async create(dto: CreateScenarioDto): Promise<ScenarioEntity> {
return this.scenarioRepo.save(this.scenarioRepo.create(dto)); const scenario = await this.scenarioRepo.save(
this.scenarioRepo.create({ ...dto, version: 1 }),
);
await this.commitVersion(scenario.id);
return this.findOne(scenario.id);
} }
async findAll( async findAll(
@@ -145,7 +272,9 @@ export class ScenarioService {
async update(id: string, dto: UpdateScenarioDto): Promise<ScenarioEntity> { async update(id: string, dto: UpdateScenarioDto): Promise<ScenarioEntity> {
const scenario = await this.findOne(id); const scenario = await this.findOne(id);
Object.assign(scenario, dto); Object.assign(scenario, dto);
return this.scenarioRepo.save(scenario); await this.scenarioRepo.save(scenario);
await this.commitVersion(id);
return this.findOne(id);
} }
async remove(id: string): Promise<void> { async remove(id: string): Promise<void> {
@@ -185,6 +314,7 @@ export class ScenarioService {
}), }),
); );
await this.normalizeStepOrder(scenarioId); await this.normalizeStepOrder(scenarioId);
await this.commitVersion(scenarioId);
return this.findStep(scenarioId, created.id); return this.findStep(scenarioId, created.id);
} }
@@ -243,6 +373,7 @@ export class ScenarioService {
await this.normalizeStepOrder(scenarioId); await this.normalizeStepOrder(scenarioId);
} }
await this.commitVersion(scenarioId);
return this.findStep(scenarioId, stepId); return this.findStep(scenarioId, stepId);
} }
@@ -250,6 +381,7 @@ export class ScenarioService {
await this.findStep(scenarioId, stepId); await this.findStep(scenarioId, stepId);
await this.stepRepo.delete(stepId); await this.stepRepo.delete(stepId);
await this.normalizeStepOrder(scenarioId); await this.normalizeStepOrder(scenarioId);
await this.commitVersion(scenarioId);
} }
// ── Scenario Credentials ────────────────────────────────────────────────── // ── Scenario Credentials ──────────────────────────────────────────────────
@@ -343,19 +475,22 @@ export class ScenarioService {
* Returns the snippets referenced (directly, or transitively via other snippets) * Returns the snippets referenced (directly, or transitively via other snippets)
* by this scenario's step code, in discovery order - for linking to them from the UI. * by this scenario's step code, in discovery order - for linking to them from the UI.
*/ */
async getUsedSnippets(scenarioId: string): Promise<SnippetEntity[]> { async getUsedSnippets(scenarioId: string): Promise<UsedSnippet[]> {
const scenario = await this.findOne(scenarioId); const scenario = await this.findOne(scenarioId);
const snippetMap = await this.snippetService.buildSnippetMap(); const snippetMap = await this.snippetService.buildSnippetMap();
const usedAliases = resolveUsedSnippetAliases( const usedRefs = resolveUsedSnippetAliases(
scenario.steps.map((s) => s.execCode ?? ""), scenario.steps.map((s) => s.execCode ?? ""),
snippetMap, snippetMap,
); ).map(parseSnippetRef);
if (usedAliases.length === 0) return []; if (usedRefs.length === 0) return [];
const snippets = await this.snippetService.findByAliases(usedAliases); const snippets = await this.snippetService.findByAliases([
...new Set(usedRefs.map((r) => r.alias)),
]);
const byAlias = new Map(snippets.map((s) => [s.alias, s])); const byAlias = new Map(snippets.map((s) => [s.alias, s]));
return usedAliases return usedRefs.flatMap(({ alias, version }) => {
.map((alias) => byAlias.get(alias)) const snippet = byAlias.get(alias);
.filter((s): s is SnippetEntity => s != null); return snippet ? [{ ...snippet, pinnedVersion: version }] : [];
});
} }
// ── Runs ────────────────────────────────────────────────────────────────── // ── Runs ──────────────────────────────────────────────────────────────────
@@ -500,8 +635,13 @@ export class ScenarioService {
environmentId: string, environmentId: string,
saveSession = false, saveSession = false,
traceMode?: TraceMode, traceMode?: TraceMode,
version?: number,
): Promise<ScenarioRunEntity> { ): Promise<ScenarioRunEntity> {
const scenario = await this.findOne(scenarioId); const scenario = await this.findOne(scenarioId);
const scenarioVersion = await this.findVersion(
scenarioId,
version ?? scenario.version,
);
const environment = await this.environmentRepo.findOneBy({ const environment = await this.environmentRepo.findOneBy({
id: environmentId, id: environmentId,
}); });
@@ -516,14 +656,19 @@ export class ScenarioService {
status: "pending", status: "pending",
saveSession, saveSession,
traceMode: traceMode ?? this.getRunDefaults().traceMode, traceMode: traceMode ?? this.getRunDefaults().traceMode,
scenarioVersion: scenarioVersion.version,
}), }),
); );
const stepRuns = scenario.steps.map((step, index) => const liveStepIds = new Set(scenario.steps.map((s) => s.id));
const stepRuns = scenarioVersion.steps.map((step, index) =>
this.runStepRepo.create({ this.runStepRepo.create({
runId: run.id, runId: run.id,
scenarioStepId: step.id, scenarioStepId: step.id && liveStepIds.has(step.id) ? step.id : null,
order: step.order, order: step.order,
title: step.title,
execCode: step.execCode,
timeoutSeconds: step.timeoutSeconds,
status: index === 0 ? "pending" : "waiting", status: index === 0 ? "pending" : "waiting",
description: null, description: null,
}), }),
@@ -542,9 +687,18 @@ export class ScenarioService {
async exportScenario( async exportScenario(
id: string, id: string,
options: { includeEnvironment: boolean; credentialIds: string[] }, options: {
includeEnvironment: boolean;
credentialIds: string[];
/** Version to export; defaults to the latest. */
version?: number;
},
): Promise<ExportEntity[]> { ): Promise<ExportEntity[]> {
const scenario = await this.findOne(id); const scenario = await this.findOne(id);
const content = await this.findVersion(
id,
options.version ?? scenario.version,
);
const entities: ExportEntity[] = []; const entities: ExportEntity[] = [];
// Include environment entity if requested and linked // Include environment entity if requested and linked
@@ -591,13 +745,16 @@ export class ScenarioService {
const scenarioDto: ScenarioExportDto = { const scenarioDto: ScenarioExportDto = {
kind: "scenario", kind: "scenario",
id: scenario.id, id: scenario.id,
name: scenario.name, version: content.version,
description: scenario.description ?? undefined, name: content.name,
environmentId: scenario.environmentId ?? undefined, description: content.description ?? undefined,
environmentId: content.environmentId ?? undefined,
timeoutSeconds: content.timeoutSeconds ?? undefined,
credentials: credentialMappings.length > 0 ? credentialMappings : undefined, credentials: credentialMappings.length > 0 ? credentialMappings : undefined,
steps: scenario.steps.map((s) => ({ steps: content.steps.map((s) => ({
title: s.title, title: s.title,
execCode: s.execCode, execCode: s.execCode,
...(s.timeoutSeconds != null ? { timeoutSeconds: s.timeoutSeconds } : {}),
})), })),
}; };
entities.push(scenarioDto); entities.push(scenarioDto);
@@ -678,46 +835,72 @@ export class ScenarioService {
throw new BadRequestException("steps must be an array"); throw new BadRequestException("steps must be an array");
} }
if (!Number.isInteger(scenarioDto.version) || scenarioDto.version < 1) {
throw new BadRequestException("version must be a positive integer");
}
// Restore the exported version: upsert by id + version. An existing
// version is left untouched; a new one is stored under its number and
// becomes the latest when it is higher than the current latest.
const dto = scenarioDto; const dto = scenarioDto;
const content: ScenarioContent = {
name: dto.name,
description: dto.description ?? null,
environmentId: dto.environmentId ?? null,
timeoutSeconds: dto.timeoutSeconds ?? null,
steps: dto.steps.map((s, index) => ({
id: null,
order: index + 1,
title: s.title ?? null,
execCode: s.execCode ?? null,
timeoutSeconds: s.timeoutSeconds ?? null,
})),
};
const existing = dto.id
? await this.scenarioRepo.findOneBy({ id: dto.id })
: null;
let scenario: ScenarioEntity; let scenario: ScenarioEntity;
if (dto.id) { if (!existing) {
const existing = await this.scenarioRepo.findOneBy({ id: dto.id });
if (existing) {
existing.name = dto.name;
existing.description = dto.description ?? null;
existing.environmentId = dto.environmentId ?? existing.environmentId;
scenario = await this.scenarioRepo.save(existing);
await this.stepRepo.delete({ scenarioId: scenario.id });
} else {
scenario = await this.scenarioRepo.save(
this.scenarioRepo.create({
id: dto.id,
name: dto.name,
description: dto.description ?? null,
environmentId: dto.environmentId ?? null,
}),
);
}
} else {
scenario = await this.scenarioRepo.save( scenario = await this.scenarioRepo.save(
this.scenarioRepo.create({ this.scenarioRepo.create({
name: dto.name, ...(dto.id ? { id: dto.id } : {}),
description: dto.description ?? null, name: content.name,
environmentId: dto.environmentId ?? null, description: content.description,
environmentId: content.environmentId,
timeoutSeconds: content.timeoutSeconds,
version: dto.version,
}), }),
); );
} await this.replaceSteps(scenario.id, content.steps);
if (dto.steps.length > 0) { await this.commitVersion(scenario.id);
const steps = dto.steps.map((s, index) => } else {
this.stepRepo.create({ scenario = existing;
scenarioId: scenario.id, const hasVersion = await this.versionRepo.existsBy({
order: index, scenarioId: existing.id,
title: s.title ?? null, version: dto.version,
execCode: s.execCode ?? null, });
}), if (!hasVersion) {
); if (dto.version > existing.version) {
await this.stepRepo.save(steps); Object.assign(existing, {
await this.normalizeStepOrder(scenario.id); name: content.name,
description: content.description,
environmentId: content.environmentId ?? existing.environmentId,
timeoutSeconds: content.timeoutSeconds,
version: dto.version,
});
scenario = await this.scenarioRepo.save(existing);
await this.replaceSteps(scenario.id, content.steps);
await this.commitVersion(scenario.id);
} else {
await this.versionRepo.save(
this.versionRepo.create({
scenarioId: existing.id,
version: dto.version,
...content,
}),
);
}
}
} }
// Restore credential alias mappings // Restore credential alias mappings
if (dto.credentials && dto.credentials.length > 0) { if (dto.credentials && dto.credentials.length > 0) {
@@ -734,6 +917,26 @@ export class ScenarioService {
return this.findOne(scenario.id); return this.findOne(scenario.id);
} }
private async replaceSteps(
scenarioId: string,
steps: ScenarioStepSnapshot[],
): Promise<void> {
await this.stepRepo.delete({ scenarioId });
if (steps.length === 0) return;
await this.stepRepo.save(
steps.map((s) =>
this.stepRepo.create({
scenarioId,
order: s.order,
title: s.title,
execCode: s.execCode,
timeoutSeconds: s.timeoutSeconds,
}),
),
);
await this.normalizeStepOrder(scenarioId);
}
// ── Files ───────────────────────────────────────────────────────────────── // ── Files ─────────────────────────────────────────────────────────────────
async uploadFile( async uploadFile(
@@ -1,6 +1,8 @@
import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger"; import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
import { import {
IsIn, IsIn,
IsInt,
Min,
IsNotEmpty, IsNotEmpty,
IsOptional, IsOptional,
IsString, IsString,
@@ -18,6 +20,11 @@ export class SnippetExportDto {
@IsUUID() @IsUUID()
id?: string; id?: string;
@ApiProperty({ description: "Snippet version this export holds" })
@IsInt()
@Min(1)
version: number;
@ApiPropertyOptional() @ApiPropertyOptional()
@IsOptional() @IsOptional()
@IsString() @IsString()
@@ -0,0 +1,47 @@
import {
Column,
CreateDateColumn,
Entity,
JoinColumn,
ManyToOne,
PrimaryGeneratedColumn,
Unique,
} from "typeorm";
import { SnippetEntity } from "./snippet.entity";
/**
* Immutable snapshot of a snippet at one version. The `snippets` table always
* holds the latest version. Step code pins a version with
* `runSnippet("alias@<version>")`.
*/
@Entity("snippet_versions")
@Unique(["snippetId", "version"])
export class SnippetVersionEntity {
@PrimaryGeneratedColumn("uuid")
id: string;
@Column("text")
snippetId: string;
@ManyToOne(() => SnippetEntity, { onDelete: "CASCADE" })
@JoinColumn({ name: "snippetId" })
snippet: SnippetEntity;
@Column({ type: "int" })
version: number;
@Column()
alias: string;
@Column({ default: "" })
title: string;
@Column("text", { nullable: true })
description: string | null;
@Column("text")
code: string;
@CreateDateColumn()
createdAt: Date;
}
+25 -2
View File
@@ -5,6 +5,7 @@ import {
Get, Get,
HttpCode, HttpCode,
Param, Param,
ParseIntPipe,
ParseUUIDPipe, ParseUUIDPipe,
Patch, Patch,
Post, Post,
@@ -48,9 +49,31 @@ export class SnippetController {
@ApiOperation({ summary: "Export a snippet as a plain object" }) @ApiOperation({ summary: "Export a snippet as a plain object" })
@ApiResponse({ status: 200, description: "Snippet export payload" }) @ApiResponse({ status: 200, description: "Snippet export payload" })
@ApiResponse({ status: 404, description: "Snippet not found" }) @ApiResponse({ status: 404, description: "Snippet not found" })
async exportSnippet(@Param("id", ParseUUIDPipe) id: string) { async exportSnippet(
@Param("id", ParseUUIDPipe) id: string,
@Query("version", new ParseIntPipe({ optional: true })) version?: number,
) {
const snippet = await this.snippetService.findOne(id); const snippet = await this.snippetService.findOne(id);
return this.snippetService.exportSnippet(snippet); return this.snippetService.exportSnippet(snippet, version);
}
@Get(":id/versions")
@ApiOperation({ summary: "List a snippet's versions, newest first" })
@ApiResponse({ status: 200, description: "Snippet versions" })
@ApiResponse({ status: 404, description: "Snippet not found" })
listVersions(@Param("id", ParseUUIDPipe) id: string) {
return this.snippetService.listVersions(id);
}
@Get(":id/versions/:version")
@ApiOperation({ summary: "Get one version of a snippet" })
@ApiResponse({ status: 200, description: "Snippet version" })
@ApiResponse({ status: 404, description: "Snippet or version not found" })
findVersion(
@Param("id", ParseUUIDPipe) id: string,
@Param("version", ParseIntPipe) version: number,
) {
return this.snippetService.findVersion(id, version);
} }
@Get(":id") @Get(":id")
+4
View File
@@ -30,6 +30,10 @@ export class SnippetEntity {
@Column("text") @Column("text")
code: string; code: string;
/** Latest version number; incremented whenever the snippet changes. */
@Column({ type: "int", default: 1 })
version: number;
@CreateDateColumn() @CreateDateColumn()
createdAt: Date; createdAt: Date;
+2 -1
View File
@@ -2,10 +2,11 @@ import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm"; import { TypeOrmModule } from "@nestjs/typeorm";
import { SnippetController } from "./snippet.controller"; import { SnippetController } from "./snippet.controller";
import { SnippetEntity } from "./snippet.entity"; import { SnippetEntity } from "./snippet.entity";
import { SnippetVersionEntity } from "./snippet-version.entity";
import { SnippetService } from "./snippet.service"; import { SnippetService } from "./snippet.service";
@Module({ @Module({
imports: [TypeOrmModule.forFeature([SnippetEntity])], imports: [TypeOrmModule.forFeature([SnippetEntity, SnippetVersionEntity])],
controllers: [SnippetController], controllers: [SnippetController],
providers: [SnippetService], providers: [SnippetService],
exports: [SnippetService], exports: [SnippetService],
+154 -35
View File
@@ -5,7 +5,7 @@ import {
OnModuleInit, OnModuleInit,
} from "@nestjs/common"; } from "@nestjs/common";
import { InjectRepository } from "@nestjs/typeorm"; import { InjectRepository } from "@nestjs/typeorm";
import { In, Repository } from "typeorm"; import { In, Not, Repository } from "typeorm";
import { import {
PaginatedResult, PaginatedResult,
PaginationQueryDto, PaginationQueryDto,
@@ -13,8 +13,20 @@ import {
import { CreateSnippetDto } from "./dto/create-snippet.dto"; import { CreateSnippetDto } from "./dto/create-snippet.dto";
import { SnippetExportDto } from "./dto/snippet-export.dto"; import { SnippetExportDto } from "./dto/snippet-export.dto";
import { UpdateSnippetDto } from "./dto/update-snippet.dto"; import { UpdateSnippetDto } from "./dto/update-snippet.dto";
import { SnippetVersionEntity } from "./snippet-version.entity";
import { SnippetEntity } from "./snippet.entity"; import { SnippetEntity } from "./snippet.entity";
type SnippetContent = Pick<
SnippetEntity,
"alias" | "title" | "description" | "code"
>;
const sameContent = (a: SnippetContent, b: SnippetContent): boolean =>
a.alias === b.alias &&
a.title === b.title &&
(a.description ?? null) === (b.description ?? null) &&
a.code === b.code;
export type SnippetOrderBy = export type SnippetOrderBy =
| "id" | "id"
| "alias" | "alias"
@@ -27,6 +39,8 @@ export class SnippetService implements OnModuleInit {
constructor( constructor(
@InjectRepository(SnippetEntity) @InjectRepository(SnippetEntity)
private readonly repo: Repository<SnippetEntity>, private readonly repo: Repository<SnippetEntity>,
@InjectRepository(SnippetVersionEntity)
private readonly versionRepo: Repository<SnippetVersionEntity>,
) {} ) {}
async onModuleInit(): Promise<void> { async onModuleInit(): Promise<void> {
@@ -47,6 +61,32 @@ export class SnippetService implements OnModuleInit {
"UPDATE snippets SET title = COALESCE(alias, '') WHERE title IS NULL OR title = ''", "UPDATE snippets SET title = COALESCE(alias, '') WHERE title IS NULL OR title = ''",
); );
} }
await this.backfillVersions();
}
/** Records the current content of snippets that have no row for their current version yet. */
private async backfillVersions(): Promise<void> {
const snippets = await this.repo.find();
for (const snippet of snippets) {
const exists = await this.versionRepo.existsBy({
snippetId: snippet.id,
version: snippet.version,
});
if (!exists) await this.recordVersion(snippet);
}
}
private recordVersion(snippet: SnippetEntity): Promise<SnippetVersionEntity> {
return this.versionRepo.save(
this.versionRepo.create({
snippetId: snippet.id,
version: snippet.version,
alias: snippet.alias,
title: snippet.title,
description: snippet.description,
code: snippet.code,
}),
);
} }
async create(dto: CreateSnippetDto): Promise<SnippetEntity> { async create(dto: CreateSnippetDto): Promise<SnippetEntity> {
@@ -56,14 +96,17 @@ export class SnippetService implements OnModuleInit {
`Snippet alias "${dto.alias}" already exists`, `Snippet alias "${dto.alias}" already exists`,
); );
} }
return this.repo.save( const snippet = await this.repo.save(
this.repo.create({ this.repo.create({
alias: dto.alias, alias: dto.alias,
title: dto.title, title: dto.title,
description: dto.description ?? null, description: dto.description ?? null,
code: dto.code, code: dto.code,
version: 1,
}), }),
); );
await this.recordVersion(snippet);
return snippet;
} }
async findAll( async findAll(
@@ -96,8 +139,37 @@ export class SnippetService implements OnModuleInit {
`Snippet alias "${dto.alias}" already exists`, `Snippet alias "${dto.alias}" already exists`,
); );
} }
Object.assign(snippet, dto); const next: SnippetContent = {
return this.repo.save(snippet); alias: dto.alias ?? snippet.alias,
title: dto.title ?? snippet.title,
description:
dto.description !== undefined ? dto.description : snippet.description,
code: dto.code ?? snippet.code,
};
if (sameContent(snippet, next)) return snippet;
Object.assign(snippet, next, { version: snippet.version + 1 });
const saved = await this.repo.save(snippet);
await this.recordVersion(saved);
return saved;
}
// ── Versions ──────────────────────────────────────────────────────────────
async listVersions(id: string): Promise<SnippetVersionEntity[]> {
await this.findOne(id); // 404 guard
return this.versionRepo.find({
where: { snippetId: id },
order: { version: "DESC" },
});
}
async findVersion(id: string, version: number): Promise<SnippetVersionEntity> {
await this.findOne(id); // 404 guard
const row = await this.versionRepo.findOneBy({ snippetId: id, version });
if (!row) {
throw new NotFoundException(`Snippet ${id} has no version ${version}`);
}
return row;
} }
async remove(id: string): Promise<void> { async remove(id: string): Promise<void> {
@@ -105,10 +177,25 @@ export class SnippetService implements OnModuleInit {
await this.repo.delete(id); await this.repo.delete(id);
} }
/** Returns an alias→code map for all snippets (used by the executor). */ /**
* Returns the code map used by the executor: `alias` → latest code, plus
* `alias@<version>` → that version's code for every stored version. Pinned
* references use the snippet's current alias.
*/
async buildSnippetMap(): Promise<Record<string, string>> { async buildSnippetMap(): Promise<Record<string, string>> {
const { data } = await this.findAll({ limit: 1000 }); const { data } = await this.findAll({ limit: 1000 });
return Object.fromEntries(data.map((s) => [s.alias, s.code])); const map: Record<string, string> = Object.fromEntries(
data.map((s) => [s.alias, s.code]),
);
if (data.length === 0) return map;
const aliasById = new Map(data.map((s) => [s.id, s.alias]));
const versions = await this.versionRepo.find({
where: { snippetId: In([...aliasById.keys()]) },
});
for (const v of versions) {
map[`${aliasById.get(v.snippetId)}@${v.version}`] = v.code;
}
return map;
} }
/** Returns the snippet entities matching the given aliases (used by executor/executor consumers). */ /** Returns the snippet entities matching the given aliases (used by executor/executor consumers). */
@@ -117,52 +204,84 @@ export class SnippetService implements OnModuleInit {
return this.repo.find({ where: { alias: In(aliases) } }); return this.repo.find({ where: { alias: In(aliases) } });
} }
exportSnippet(snippet: SnippetEntity): SnippetExportDto { /** Exports the latest version, or `version` when given. */
async exportSnippet(
snippet: SnippetEntity,
version?: number,
): Promise<SnippetExportDto> {
const content: SnippetContent & { version: number } =
version === undefined || version === snippet.version
? snippet
: await this.findVersion(snippet.id, version);
return { return {
kind: "snippet", kind: "snippet",
id: snippet.id, id: snippet.id,
alias: snippet.alias, version: content.version,
title: snippet.title, alias: content.alias,
description: snippet.description, title: content.title,
code: snippet.code, description: content.description,
code: content.code,
}; };
} }
/**
* Restores the exported version: upsert by id + version. An existing version
* is left untouched; a new one is stored under its number and becomes the
* latest when it is higher than the current latest.
*/
async importSnippet(dto: SnippetExportDto): Promise<SnippetEntity> { async importSnippet(dto: SnippetExportDto): Promise<SnippetEntity> {
const alias = dto.alias ?? dto.name; const alias = dto.alias ?? dto.name;
if (!alias) { if (!alias) {
throw new ConflictException("Snippet alias is required"); throw new ConflictException("Snippet alias is required");
} }
const title = dto.title ?? alias; const content: SnippetContent = {
alias,
title: dto.title ?? alias,
description: dto.description ?? null,
code: dto.code,
};
if (dto.id) { const existing = dto.id ? await this.repo.findOneBy({ id: dto.id }) : null;
const existing = await this.repo.findOneBy({ id: dto.id }); if (!existing) {
if (existing) { await this.assertAliasFree(alias);
Object.assign(existing, { const created = await this.repo.save(
alias,
title,
description: dto.description ?? null,
code: dto.code,
});
return this.repo.save(existing);
}
return this.repo.save(
this.repo.create({ this.repo.create({
id: dto.id, ...(dto.id ? { id: dto.id } : {}),
alias, ...content,
title, version: dto.version,
description: dto.description ?? null,
code: dto.code,
}), }),
); );
await this.recordVersion(created);
return created;
} }
return this.repo.save(
this.repo.create({ const hasVersion = await this.versionRepo.existsBy({
alias, snippetId: existing.id,
title, version: dto.version,
description: dto.description ?? null, });
code: dto.code, if (hasVersion) return existing;
await this.versionRepo.save(
this.versionRepo.create({
snippetId: existing.id,
version: dto.version,
...content,
}), }),
); );
if (dto.version > existing.version) {
if (alias !== existing.alias) await this.assertAliasFree(alias, existing.id);
Object.assign(existing, content, { version: dto.version });
return this.repo.save(existing);
}
return existing;
}
private async assertAliasFree(alias: string, exceptId?: string): Promise<void> {
const conflict = await this.repo.findOneBy(
exceptId ? { alias, id: Not(exceptId) } : { alias },
);
if (conflict) {
throw new ConflictException(`Snippet alias "${alias}" already exists`);
}
} }
} }
+4
View File
@@ -38,6 +38,8 @@ import { SessionEntity } from "../src/session/session.entity";
import { EnvironmentEntity } from "../src/environment/environment.entity"; import { EnvironmentEntity } from "../src/environment/environment.entity";
import { ScenarioEntity } from "../src/scenario/scenario.entity"; import { ScenarioEntity } from "../src/scenario/scenario.entity";
import { ScenarioStepEntity } from "../src/scenario/scenario-step.entity"; import { ScenarioStepEntity } from "../src/scenario/scenario-step.entity";
import { ScenarioVersionEntity } from "../src/scenario/scenario-version.entity";
import { SnippetVersionEntity } from "../src/snippet/snippet-version.entity";
import { ScenarioRunEntity } from "../src/scenario/scenario-run.entity"; import { ScenarioRunEntity } from "../src/scenario/scenario-run.entity";
import { ScenarioRunStepEntity } from "../src/scenario/scenario-run-step.entity"; import { ScenarioRunStepEntity } from "../src/scenario/scenario-run-step.entity";
import { ScenarioRunLogEntity } from "../src/scenario/scenario-run-log.entity"; import { ScenarioRunLogEntity } from "../src/scenario/scenario-run-log.entity";
@@ -68,12 +70,14 @@ export async function buildTestApp(): Promise<INestApplication> {
EnvironmentEntity, EnvironmentEntity,
ScenarioEntity, ScenarioEntity,
ScenarioStepEntity, ScenarioStepEntity,
ScenarioVersionEntity,
ScenarioRunEntity, ScenarioRunEntity,
ScenarioRunStepEntity, ScenarioRunStepEntity,
ScenarioRunLogEntity, ScenarioRunLogEntity,
ScenarioCredentialEntity, ScenarioCredentialEntity,
CredentialEntity, CredentialEntity,
SnippetEntity, SnippetEntity,
SnippetVersionEntity,
FileEntity, FileEntity,
ScenarioFileEntity, ScenarioFileEntity,
ScenarioRunFileEntity, ScenarioRunFileEntity,
+5
View File
@@ -133,11 +133,16 @@ describe("Exec Context File Methods Integration Tests", () => {
scenarioStepId: string, scenarioStepId: string,
order = 0, order = 0,
) { ) {
// Run steps execute from their own copy of the step content
const step = await stepRepo.findOneByOrFail({ id: scenarioStepId });
const runStep = await runStepRepo.save( const runStep = await runStepRepo.save(
runStepRepo.create({ runStepRepo.create({
runId, runId,
scenarioStepId, scenarioStepId,
order, order,
title: step.title,
execCode: step.execCode,
timeoutSeconds: step.timeoutSeconds,
status: "pending", status: "pending",
}), }),
); );
+5
View File
@@ -124,11 +124,16 @@ describe("McpController", () => {
} }
async function createRunStep(runId: string, scenarioStepId: string, order = 0) { async function createRunStep(runId: string, scenarioStepId: string, order = 0) {
// Run steps execute from their own copy of the step content
const step = await stepRepo.findOneByOrFail({ id: scenarioStepId });
return runStepRepo.save( return runStepRepo.save(
runStepRepo.create({ runStepRepo.create({
runId, runId,
scenarioStepId, scenarioStepId,
order, order,
title: step.title,
execCode: step.execCode,
timeoutSeconds: step.timeoutSeconds,
status: "pending", status: "pending",
}), }),
); );
+10 -1
View File
@@ -676,6 +676,7 @@ describe("ScenarioController", () => {
it("creates a new scenario with all steps", async () => { it("creates a new scenario with all steps", async () => {
const payload = { const payload = {
name: "imported scenario", name: "imported scenario",
version: 1,
steps: [ steps: [
{ {
sessionName: "s", sessionName: "s",
@@ -750,13 +751,20 @@ describe("ScenarioController", () => {
it("imports with empty steps array", async () => { it("imports with empty steps array", async () => {
const res = await request(app.getHttpServer()) const res = await request(app.getHttpServer())
.post("/scenarios/import") .post("/scenarios/import")
.send({ name: "empty-import", steps: [] }) .send({ name: "empty-import", version: 1, steps: [] })
.expect(201); .expect(201);
expect(res.body.name).toBe("empty-import"); expect(res.body.name).toBe("empty-import");
expect(res.body.steps).toHaveLength(0); expect(res.body.steps).toHaveLength(0);
}); });
it("returns 400 when version is missing", async () => {
await request(app.getHttpServer())
.post("/scenarios/import")
.send({ name: "no-version", steps: [] })
.expect(400);
});
it("returns 400 when name is missing", async () => { it("returns 400 when name is missing", async () => {
await request(app.getHttpServer()) await request(app.getHttpServer())
.post("/scenarios/import") .post("/scenarios/import")
@@ -776,6 +784,7 @@ describe("ScenarioController", () => {
.post("/scenarios/import") .post("/scenarios/import")
.send({ .send({
name: "bad-type", name: "bad-type",
version: 1,
steps: [{ type: "unknown", sessionName: "s" }], steps: [{ type: "unknown", sessionName: "s" }],
}) })
.expect(201); .expect(201);
+393
View File
@@ -0,0 +1,393 @@
/**
* Integration tests for scenario and snippet versioning:
* - versions bump on content changes only
* - runs record and execute the scenario version they were created with
* - runSnippet("alias@N") pins a snippet version
* - export/import carry and restore exact versions
*/
import { INestApplication } from "@nestjs/common";
import request from "supertest";
import { DataSource } from "typeorm";
import { buildTestApp } from "./app.harness";
import { CredentialEntity } from "../src/credential/credential.entity";
import { EnvironmentEntity } from "../src/environment/environment.entity";
import { ScenarioSchedulerService } from "../src/scenario/scenario-scheduler.service";
import { ScenarioService } from "../src/scenario/scenario.service";
import { SnippetService } from "../src/snippet/snippet.service";
describe("Versioning", () => {
let app: INestApplication;
let dataSource: DataSource;
let scenarioService: ScenarioService;
let snippetService: SnippetService;
let scheduler: ScenarioSchedulerService;
beforeAll(async () => {
app = await buildTestApp();
dataSource = app.get(DataSource);
scenarioService = app.get(ScenarioService);
snippetService = app.get(SnippetService);
scheduler = app.get(ScenarioSchedulerService);
});
afterAll(async () => {
await app.close();
});
// ── helpers ────────────────────────────────────────────────────────────────
const uniq = () => Math.random().toString(36).slice(2, 8);
async function createEnvironment(): Promise<string> {
const repo = dataSource.getRepository(EnvironmentEntity);
const env = await repo.save(
repo.create({ name: `env-${uniq()}`, data: {} }),
);
return env.id;
}
async function versionNumbers(scenarioId: string): Promise<number[]> {
return (await scenarioService.listVersions(scenarioId)).map(
(v) => v.version,
);
}
/** Creates and processes a run; returns it with its step runs. */
async function runToCompletion(scenarioId: string, version?: number) {
const run = await scenarioService.createRun(
scenarioId,
await createEnvironment(),
false,
undefined,
version,
);
await scheduler.pickUpPendingRuns();
return scenarioService.waitForRun(scenarioId, run.id, 10_000);
}
const outputs = (run: { stepRuns: { output: string | null }[] }) =>
run.stepRuns.map((s) => (s.output ? JSON.parse(s.output) : null));
// ── scenario versions ─────────────────────────────────────────────────────
describe("scenario versions", () => {
it("starts at version 1 with a stored snapshot", async () => {
const sc = await scenarioService.create({ name: `v-${uniq()}` });
expect(sc.version).toBe(1);
expect(await versionNumbers(sc.id)).toEqual([1]);
});
it("bumps on scenario and step changes, not on no-op updates", async () => {
const sc = await scenarioService.create({ name: `bump-${uniq()}` });
await scenarioService.update(sc.id, { name: `${sc.name}-renamed` });
expect((await scenarioService.findOne(sc.id)).version).toBe(2);
// Same content again: no new version
await scenarioService.update(sc.id, { name: `${sc.name}-renamed` });
expect((await scenarioService.findOne(sc.id)).version).toBe(2);
const step = await scenarioService.createStep(sc.id, {
execCode: "return 1;",
});
expect((await scenarioService.findOne(sc.id)).version).toBe(3);
await scenarioService.updateStep(sc.id, step.id, {
execCode: "return 2;",
});
expect((await scenarioService.findOne(sc.id)).version).toBe(4);
await scenarioService.removeStep(sc.id, step.id);
expect((await scenarioService.findOne(sc.id)).version).toBe(5);
expect(await versionNumbers(sc.id)).toEqual([5, 4, 3, 2, 1]);
const v4 = await scenarioService.findVersion(sc.id, 4);
expect(v4.steps.map((s) => s.execCode)).toEqual(["return 2;"]);
});
it("does not bump on credential assignment", async () => {
const sc = await scenarioService.create({ name: `cred-${uniq()}` });
const credRepo = dataSource.getRepository(CredentialEntity);
const cred = await credRepo.save(
credRepo.create({ name: "c", data: null }),
);
await scenarioService.addScenarioCredential(sc.id, {
credentialId: cred.id,
alias: "c",
});
expect((await scenarioService.findOne(sc.id)).version).toBe(1);
});
it("exposes versions over HTTP", async () => {
const sc = await scenarioService.create({ name: `http-${uniq()}` });
await scenarioService.createStep(sc.id, { execCode: "return 1;" });
const list = await request(app.getHttpServer())
.get(`/scenarios/${sc.id}/versions`)
.expect(200);
expect(list.body.map((v: { version: number }) => v.version)).toEqual([
2, 1,
]);
const one = await request(app.getHttpServer())
.get(`/scenarios/${sc.id}/versions/2`)
.expect(200);
expect(one.body.steps).toHaveLength(1);
await request(app.getHttpServer())
.get(`/scenarios/${sc.id}/versions/99`)
.expect(404);
});
});
// ── runs ──────────────────────────────────────────────────────────────────
describe("runs", () => {
it("runs the latest version by default and records it", async () => {
const sc = await scenarioService.create({ name: `run-${uniq()}` });
await scenarioService.createStep(sc.id, { execCode: "return 'latest';" });
const run = await runToCompletion(sc.id);
expect(run.scenarioVersion).toBe(2);
expect(outputs(run)).toEqual(["latest"]);
});
it("runs an older version's steps when asked", async () => {
const sc = await scenarioService.create({ name: `old-${uniq()}` });
const step = await scenarioService.createStep(sc.id, {
title: "first",
execCode: "return 'v2';",
});
await scenarioService.updateStep(sc.id, step.id, {
execCode: "return 'v3';",
});
await scenarioService.createStep(sc.id, { execCode: "return 'extra';" });
const run = await runToCompletion(sc.id, 2);
expect(run.scenarioVersion).toBe(2);
expect(run.stepRuns).toHaveLength(1);
expect(run.stepRuns[0].title).toBe("first");
expect(run.stepRuns[0].execCode).toBe("return 'v2';");
expect(outputs(run)).toEqual(["v2"]);
});
it("rejects a version that does not exist", async () => {
const sc = await scenarioService.create({ name: `nov-${uniq()}` });
const environmentId = await createEnvironment();
await request(app.getHttpServer())
.post(`/scenarios/${sc.id}/run`)
.send({ environmentId, version: 7 })
.expect(404);
});
it("keeps run history when a step is deleted", async () => {
const sc = await scenarioService.create({ name: `hist-${uniq()}` });
const step = await scenarioService.createStep(sc.id, {
execCode: "return 1;",
});
const run = await runToCompletion(sc.id);
await scenarioService.removeStep(sc.id, step.id);
const after = await scenarioService.findRun(sc.id, run.id);
expect(after.stepRuns).toHaveLength(1);
expect(after.stepRuns[0].scenarioStepId).toBeNull();
expect(after.stepRuns[0].execCode).toBe("return 1;");
});
});
// ── snippet versions ──────────────────────────────────────────────────────
describe("snippet versions", () => {
it("bumps on change only and keeps every version", async () => {
const alias = `snip-${uniq()}`;
const sn = await snippetService.create({
alias,
title: "t",
code: "return 1;",
});
expect(sn.version).toBe(1);
await snippetService.update(sn.id, { code: "return 2;" });
await snippetService.update(sn.id, { code: "return 2;" }); // no-op
expect((await snippetService.findOne(sn.id)).version).toBe(2);
const versions = await snippetService.listVersions(sn.id);
expect(versions.map((v) => [v.version, v.code])).toEqual([
[2, "return 2;"],
[1, "return 1;"],
]);
});
it("runSnippet uses the latest by default and alias@N pins a version", async () => {
const alias = `pin-${uniq()}`;
const sn = await snippetService.create({
alias,
title: "t",
code: "return 'one';",
});
await snippetService.update(sn.id, { code: "return 'two';" });
const sc = await scenarioService.create({ name: `pinned-${uniq()}` });
await scenarioService.createStep(sc.id, {
execCode: `return [await context.runSnippet("${alias}"), await context.runSnippet("${alias}@1")];`,
});
const run = await runToCompletion(sc.id);
expect(run.status).toBe("pass");
expect(outputs(run)).toEqual([["two", "one"]]);
const used = await scenarioService.getUsedSnippets(sc.id);
expect(used.map((u) => [u.alias, u.pinnedVersion])).toEqual([
[alias, null],
[alias, 1],
]);
});
it("fails the step for a snippet version that does not exist", async () => {
const alias = `missing-${uniq()}`;
await snippetService.create({ alias, title: "t", code: "return 1;" });
const sc = await scenarioService.create({ name: `miss-${uniq()}` });
await scenarioService.createStep(sc.id, {
execCode: `return context.runSnippet("${alias}@5");`,
});
const run = await runToCompletion(sc.id);
expect(run.status).toBe("fail");
});
});
// ── export / import ───────────────────────────────────────────────────────
describe("scenario export/import", () => {
it("exports the latest version, or the one asked for", async () => {
const sc = await scenarioService.create({ name: `exp-${uniq()}` });
await scenarioService.createStep(sc.id, { execCode: "return 1;" });
const latest = await scenarioService.exportScenario(sc.id, {
includeEnvironment: false,
credentialIds: [],
});
expect(latest[latest.length - 1]).toMatchObject({
version: 2,
steps: [{ execCode: "return 1;" }],
});
const first = await scenarioService.exportScenario(sc.id, {
includeEnvironment: false,
credentialIds: [],
version: 1,
});
expect(first[first.length - 1]).toMatchObject({ version: 1, steps: [] });
});
it("restores exact versions by id + version", async () => {
const id = crypto.randomUUID();
const base = { kind: "scenario" as const, id, name: "imported" };
// New scenario: stored under the given version
let sc = await scenarioService.importScenario({
...base,
version: 3,
steps: [{ title: null, execCode: "return 3;" }],
});
expect(sc.version).toBe(3);
expect(await versionNumbers(id)).toEqual([3]);
// Same version again: left untouched
sc = await scenarioService.importScenario({
...base,
name: "changed",
version: 3,
steps: [],
});
expect(sc.name).toBe("imported");
expect(sc.steps).toHaveLength(1);
// Lower, missing version: stored, latest unchanged
sc = await scenarioService.importScenario({
...base,
version: 1,
steps: [{ title: null, execCode: "return 1;" }],
});
expect(sc.version).toBe(3);
expect(await versionNumbers(id)).toEqual([3, 1]);
expect((await scenarioService.findVersion(id, 1)).steps[0].execCode).toBe(
"return 1;",
);
// Higher version: becomes the latest
sc = await scenarioService.importScenario({
...base,
name: "v5",
version: 5,
steps: [{ title: null, execCode: "return 5;" }],
});
expect(sc.version).toBe(5);
expect(sc.name).toBe("v5");
expect(sc.steps.map((s) => s.execCode)).toEqual(["return 5;"]);
expect(await versionNumbers(id)).toEqual([5, 3, 1]);
});
});
describe("snippet export/import", () => {
it("export includes the version and import requires it", async () => {
const alias = `sexp-${uniq()}`;
const sn = await snippetService.create({
alias,
title: "t",
code: "return 1;",
});
await snippetService.update(sn.id, { code: "return 2;" });
const latest = await request(app.getHttpServer())
.get(`/snippets/${sn.id}/export`)
.expect(200);
expect(latest.body).toMatchObject({ version: 2, code: "return 2;" });
const first = await request(app.getHttpServer())
.get(`/snippets/${sn.id}/export?version=1`)
.expect(200);
expect(first.body).toMatchObject({ version: 1, code: "return 1;" });
await request(app.getHttpServer())
.post("/snippets/import")
.send({ alias: `noversion-${uniq()}`, code: "return 0;" })
.expect(400);
});
it("restores exact versions by id + version", async () => {
const id = crypto.randomUUID();
const alias = `simp-${uniq()}`;
const base = { kind: "snippet" as const, id, alias, title: "t" };
let sn = await snippetService.importSnippet({
...base,
version: 2,
code: "return 2;",
});
expect(sn.version).toBe(2);
sn = await snippetService.importSnippet({
...base,
version: 2,
code: "changed",
});
expect(sn.code).toBe("return 2;");
sn = await snippetService.importSnippet({
...base,
version: 1,
code: "return 1;",
});
expect(sn.version).toBe(2);
sn = await snippetService.importSnippet({
...base,
version: 4,
code: "return 4;",
});
expect(sn.version).toBe(4);
expect(sn.code).toBe("return 4;");
expect(
(await snippetService.listVersions(id)).map((v) => v.version),
).toEqual([4, 2, 1]);
});
});
});