allure 3.5.0 → 3.6.0

package/README.md

@@ -60,6 +60,22 @@ To successfully generate a report, ensure that your test setup outputs results i
 
 After the tests complete, the report is generated automatically. Existing results from previous runs are ignored, as Allure 3 focuses solely on new data to ensure accurate and up-to-date reporting.
 
+### Running Tests In Agent Mode
+
+When you need agent-friendly markdown output for review, debugging, or scope validation, use the `agent` command:
+
+```bash
+npx allure agent -- <test_command>
+```
+
+For example:
+
+```bash
+npx allure agent -- npm test
+```
+
+`allure agent` runs with an agent-only profile by default. It creates a fresh output directory automatically, can load an expectations file with `--expectations`, and ignores configured presentation or export plugins such as Awesome or TestOps unless you explicitly fall back to the lower-level `ALLURE_AGENT_*` plus `allure run` flow.
+
 ### Generating Reports Manually
 
 If you already have test results and wish to generate a report manually, use the `generate` command:
@@ -102,6 +118,7 @@ The Allure CLI includes several helpful global options. Use `--help` to explore
 
 ```bash
 npx allure run --help
+npx allure agent --help
 npx allure watch --help
 ```
 

package/dist/commands/agent.d.ts

@@ -0,0 +1,58 @@
+import { Command } from "clipanion";
+export declare class AgentCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    config: string | undefined;
+    cwd: string | undefined;
+    output: string | undefined;
+    expectations: string | undefined;
+    environment: string | undefined;
+    environmentName: string | undefined;
+    silent: boolean | undefined;
+    rerunFrom: string | undefined;
+    rerunLatest: boolean | undefined;
+    rerunPreset: string | undefined;
+    rerunEnvironments: string[] | undefined;
+    rerunLabels: string[] | undefined;
+    commandToRun: string[];
+    execute(): Promise<void>;
+}
+export declare class AgentLatestCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    cwd: string | undefined;
+    execute(): Promise<void>;
+}
+export declare class AgentStateDirCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    cwd: string | undefined;
+    execute(): Promise<void>;
+}
+export declare class AgentSelectCommand extends Command {
+    static paths: string[][];
+    static usage: import("clipanion").Usage;
+    cwd: string | undefined;
+    from: string | undefined;
+    latest: boolean | undefined;
+    preset: string | undefined;
+    environments: string[] | undefined;
+    labels: string[] | undefined;
+    output: string | undefined;
+    execute(): Promise<void>;
+}
+export declare const executeAgentMode: (params: {
+    configPath?: string;
+    cwd?: string;
+    output?: string;
+    expectations?: string;
+    environment?: string;
+    environmentName?: string;
+    silent?: boolean;
+    rerunFrom?: string;
+    rerunLatest?: boolean;
+    rerunPreset?: string;
+    rerunEnvironments?: string[];
+    rerunLabels?: string[];
+    args?: string[];
+}) => Promise<void>;

package/dist/commands/agent.js

@@ -0,0 +1,374 @@
+import * as console from "node:console";
+import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import process, { exit } from "node:process";
+import { AllureReport, isFileNotFoundError, readConfig } from "@allurereport/core";
+import { Command, Option, UsageError } from "clipanion";
+import { createAgentTestPlanContext, normalizeAgentRerunPreset, parseAgentLabelFilters, resolveAgentSelectionOutputDir, selectAgentTestPlan, } from "../utils/agent-select.js";
+import { readLatestAgentState, resolveAgentStateDir, writeLatestAgentState } from "../utils/agent-state.js";
+import { environmentNameOption, environmentOption, normalizeCommandEnvironmentOptions, resolveCommandEnvironment, } from "../utils/environment.js";
+import { createChildAllureCliEnvironment, getActiveAllureCliCommand } from "../utils/execution-context.js";
+import { executeAllureRun, executeNestedAllureCommand } from "./commons/run.js";
+const withProcessEnv = async (overrides, fn) => {
+    const previousValues = new Map();
+    for (const [key, value] of Object.entries(overrides)) {
+        previousValues.set(key, process.env[key]);
+        if (value === undefined) {
+            delete process.env[key];
+            continue;
+        }
+        process.env[key] = value;
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        for (const [key, value] of previousValues) {
+            if (value === undefined) {
+                delete process.env[key];
+                continue;
+            }
+            process.env[key] = value;
+        }
+    }
+};
+const isPathInside = (parentPath, candidatePath) => {
+    const rel = relative(parentPath, candidatePath);
+    return rel === "" || (!rel.startsWith("..") && rel !== "." && !rel.startsWith("../"));
+};
+const persistLatestAgentState = async (value) => {
+    try {
+        await writeLatestAgentState(value);
+    }
+    catch (error) {
+        console.error(`Could not update latest agent output in ${resolveAgentStateDir(value.cwd)}: ${error.message}`);
+    }
+};
+const readOptionalString = (value) => (typeof value === "string" ? value : undefined);
+const readOptionalBoolean = (value) => value === true;
+const readOptionalStringArray = (value) => (Array.isArray(value) ? value : undefined);
+export class AgentCommand extends Command {
+    constructor() {
+        super(...arguments);
+        this.config = Option.String("--config,-c", {
+            description: "The path Allure config file",
+        });
+        this.cwd = Option.String("--cwd", {
+            description: "The working directory for the command to run (default: current working directory)",
+        });
+        this.output = Option.String("--output,-o", {
+            description: "The output directory for agent artifacts. Absolute paths are accepted as well",
+        });
+        this.expectations = Option.String("--expectations", {
+            description: "The path to a YAML or JSON expectations file",
+        });
+        this.environment = environmentOption();
+        this.environmentName = environmentNameOption();
+        this.silent = Option.Boolean("--silent", {
+            description: "Don't pipe the process output logs to console (default: false)",
+        });
+        this.rerunFrom = Option.String("--rerun-from", {
+            description: "Select tests for rerun from an existing agent output directory",
+        });
+        this.rerunLatest = Option.Boolean("--rerun-latest", {
+            description: "Select tests for rerun from the latest recorded agent output for the current project",
+        });
+        this.rerunPreset = Option.String("--rerun-preset", {
+            description: "The rerun selection preset: review, failed, unsuccessful, or all (default: review)",
+        });
+        this.rerunEnvironments = Option.Array("--rerun-environment", {
+            description: "Filter rerun selection by environment id. Repeat the option for multiple environments",
+        });
+        this.rerunLabels = Option.Array("--rerun-label", {
+            description: "Filter rerun selection by exact label name=value. Repeat the option for multiple filters",
+        });
+        this.commandToRun = Option.Rest();
+    }
+    async execute() {
+        const args = this.commandToRun.filter((arg) => arg !== "--");
+        await executeAgentMode({
+            configPath: readOptionalString(this.config),
+            cwd: readOptionalString(this.cwd),
+            output: readOptionalString(this.output),
+            expectations: readOptionalString(this.expectations),
+            environment: readOptionalString(this.environment),
+            environmentName: readOptionalString(this.environmentName),
+            silent: readOptionalBoolean(this.silent),
+            rerunFrom: readOptionalString(this.rerunFrom),
+            rerunLatest: readOptionalBoolean(this.rerunLatest),
+            rerunPreset: readOptionalString(this.rerunPreset),
+            rerunEnvironments: readOptionalStringArray(this.rerunEnvironments),
+            rerunLabels: readOptionalStringArray(this.rerunLabels),
+            args,
+        });
+    }
+}
+AgentCommand.paths = [["agent"]];
+AgentCommand.usage = Command.Usage({
+    description: "Run specified command in Allure agent mode",
+    details: "This command runs the specified command with an agent-only Allure profile.",
+    examples: [
+        ["agent -- npm test", "Run npm test and capture only the agent-mode output"],
+        [
+            "agent --expectations ./expected.yaml -- npm test",
+            "Run npm test with agent-mode expectations loaded from ./expected.yaml",
+        ],
+    ],
+});
+export class AgentLatestCommand extends Command {
+    constructor() {
+        super(...arguments);
+        this.cwd = Option.String("--cwd", {
+            description: "The project directory used to resolve the latest agent output (default: current working directory)",
+        });
+    }
+    async execute() {
+        const cwd = await realpath(this.cwd ?? process.cwd());
+        let latestState;
+        try {
+            latestState = await readLatestAgentState(cwd);
+        }
+        catch (error) {
+            console.error(`Could not read the latest agent output for ${cwd}: ${error.message}`);
+            exit(1);
+            return;
+        }
+        if (!latestState) {
+            console.error(`No latest agent output found for ${cwd}`);
+            exit(1);
+            return;
+        }
+        console.log(latestState.outputDir);
+    }
+}
+AgentLatestCommand.paths = [["agent", "latest"]];
+AgentLatestCommand.usage = Command.Usage({
+    description: "Print the latest Allure agent output directory for the current project",
+    details: "This command prints the latest agent output directory recorded for the resolved project cwd.",
+    examples: [
+        ["agent latest", "Print the latest agent output directory for the current project"],
+        ["agent latest --cwd ./packages/cli", "Print the latest agent output directory for a specific project cwd"],
+    ],
+});
+export class AgentStateDirCommand extends Command {
+    constructor() {
+        super(...arguments);
+        this.cwd = Option.String("--cwd", {
+            description: "The project directory used to resolve the agent state directory (default: current working directory)",
+        });
+    }
+    async execute() {
+        const cwd = await realpath(readOptionalString(this.cwd) ?? process.cwd());
+        console.log(resolveAgentStateDir(cwd));
+    }
+}
+AgentStateDirCommand.paths = [["agent", "state-dir"]];
+AgentStateDirCommand.usage = Command.Usage({
+    description: "Print the Allure agent state directory for the current project",
+    details: "This command prints the resolved state directory used to persist latest-agent pointers for the current project cwd.",
+    examples: [
+        ["agent state-dir", "Print the resolved state directory for the current project"],
+        ["agent state-dir --cwd ./packages/cli", "Print the resolved state directory for a specific project cwd"],
+    ],
+});
+export class AgentSelectCommand extends Command {
+    constructor() {
+        super(...arguments);
+        this.cwd = Option.String("--cwd", {
+            description: "The project directory used to resolve --latest and relative paths (default: current working directory)",
+        });
+        this.from = Option.String("--from", {
+            description: "The prior agent output directory to select tests from",
+        });
+        this.latest = Option.Boolean("--latest", {
+            description: "Use the latest recorded agent output for the current project cwd",
+        });
+        this.preset = Option.String("--preset", {
+            description: "The selection preset: review, failed, unsuccessful, or all (default: review)",
+        });
+        this.environments = Option.Array("--environment", {
+            description: "Filter selected tests by environment id. Repeat the option for multiple environments",
+        });
+        this.labels = Option.Array("--label", {
+            description: "Filter selected tests by exact label name=value. Repeat the option for multiple filters",
+        });
+        this.output = Option.String("--output,-o", {
+            description: "Write the resulting test plan to this file instead of printing it to stdout",
+        });
+    }
+    async execute() {
+        const cwd = await realpath(readOptionalString(this.cwd) ?? process.cwd());
+        const environments = readOptionalStringArray(this.environments);
+        const labels = readOptionalStringArray(this.labels);
+        const outputDir = await resolveAgentSelectionOutputDir({
+            cwd,
+            from: readOptionalString(this.from),
+            latest: readOptionalBoolean(this.latest),
+        });
+        const selection = await selectAgentTestPlan({
+            outputDir,
+            preset: normalizeAgentRerunPreset(readOptionalString(this.preset)),
+            environments: environments?.length ? environments : undefined,
+            labelFilters: parseAgentLabelFilters(labels),
+        });
+        if (!selection.testPlan.tests.length) {
+            console.error(`No tests matched selection in ${selection.outputDir}`);
+            exit(1);
+            return;
+        }
+        const serialized = `${JSON.stringify(selection.testPlan, null, 2)}\n`;
+        const output = readOptionalString(this.output);
+        if (!output) {
+            console.log(serialized.trimEnd());
+            return;
+        }
+        const outputPath = resolve(cwd, output);
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, serialized, "utf-8");
+        console.log(outputPath);
+    }
+}
+AgentSelectCommand.paths = [["agent", "select"]];
+AgentSelectCommand.usage = Command.Usage({
+    description: "Select tests from an existing agent output and emit a test plan",
+    details: "This command resolves a set of tests from a prior agent run and prints or writes a testplan.json payload.",
+    examples: [
+        ["agent select --from ./out/agent-output", "Print a test plan for the default review-targeted tests"],
+        ["agent select --latest --preset failed", "Print a test plan for failed tests from the latest project run"],
+        ["agent select --from ./out/agent-output --output ./testplan.json", "Write the selected test plan to a file"],
+    ],
+});
+export const executeAgentMode = async (params) => {
+    const { configPath, cwd: configuredCwd, output, expectations, environment, environmentName, silent, rerunFrom, rerunLatest, rerunPreset, rerunEnvironments, rerunLabels, args, } = params;
+    if (!args || !args.length) {
+        throw new UsageError("expecting command to be specified after --, e.g. allure agent -- npm run test");
+    }
+    const command = args[0];
+    const commandArgs = args.slice(1);
+    const cwd = await realpath(configuredCwd ?? process.cwd());
+    const commandString = `${command} ${commandArgs.join(" ")}`;
+    const hasRerunSource = !!rerunFrom || !!rerunLatest;
+    const hasRerunFilters = !!rerunPreset || !!rerunEnvironments?.length || !!rerunLabels?.length;
+    if (!hasRerunSource && hasRerunFilters) {
+        throw new UsageError("Use rerun filters only together with --rerun-from <path> or --rerun-latest");
+    }
+    const rerunContext = await createAgentTestPlanContext({
+        cwd,
+        from: rerunFrom,
+        latest: rerunLatest,
+        preset: normalizeAgentRerunPreset(rerunPreset),
+        environments: rerunEnvironments?.length ? rerunEnvironments : undefined,
+        labelFilters: parseAgentLabelFilters(rerunLabels),
+    });
+    const childEnvironmentVariables = {
+        ...createChildAllureCliEnvironment("agent"),
+        ...(rerunContext ? { ALLURE_TESTPLAN_PATH: rerunContext.testPlanPath } : {}),
+    };
+    try {
+        if (getActiveAllureCliCommand()) {
+            console.log(commandString);
+            const exitCode = await executeNestedAllureCommand({
+                command,
+                commandArgs,
+                cwd,
+                ...(rerunContext ? { environmentVariables: { ALLURE_TESTPLAN_PATH: rerunContext.testPlanPath } } : {}),
+                silent,
+            });
+            exit(exitCode ?? -1);
+            return;
+        }
+        const outputDir = output ? resolve(cwd, output) : await mkdtemp(join(tmpdir(), "allure-agent-"));
+        const expectationsPath = expectations ? resolve(cwd, expectations) : undefined;
+        const environmentOptions = {
+            environment,
+            environmentName,
+        };
+        normalizeCommandEnvironmentOptions(environmentOptions);
+        if (expectationsPath && isPathInside(outputDir, expectationsPath)) {
+            throw new UsageError(`--expectations path ${JSON.stringify(expectationsPath)} must not be inside the agent output directory ${JSON.stringify(outputDir)}`);
+        }
+        const config = await readConfig(cwd, configPath, {
+            output: outputDir,
+            plugins: {
+                agent: {
+                    options: {
+                        outputDir,
+                    },
+                },
+            },
+        });
+        const resolvedEnvironment = resolveCommandEnvironment(config, environmentOptions);
+        try {
+            await rm(outputDir, { recursive: true });
+        }
+        catch (error) {
+            if (!isFileNotFoundError(error)) {
+                console.error("could not clean output directory", error);
+            }
+        }
+        const startedAt = new Date().toISOString();
+        await persistLatestAgentState({
+            cwd,
+            outputDir,
+            expectationsPath,
+            command: commandString,
+            startedAt,
+            status: "running",
+        });
+        console.log(`agent output: ${outputDir}`);
+        if (expectationsPath) {
+            console.log(`agent expectations: ${expectationsPath}`);
+        }
+        console.log(commandString);
+        const allureReport = new AllureReport({
+            ...config,
+            output: outputDir,
+            environment: resolvedEnvironment?.id,
+            open: false,
+            port: undefined,
+            qualityGate: undefined,
+            allureService: undefined,
+            realTime: false,
+            plugins: config.plugins,
+        });
+        const knownIssues = await allureReport.store.allKnownIssues();
+        const { globalExitCode } = await withProcessEnv({
+            ALLURE_AGENT_OUTPUT: outputDir,
+            ALLURE_AGENT_EXPECTATIONS: expectationsPath,
+            ALLURE_AGENT_COMMAND: commandString,
+            ALLURE_AGENT_PROJECT_ROOT: cwd,
+            ALLURE_AGENT_NAME: undefined,
+            ALLURE_AGENT_LOOP_ID: undefined,
+            ALLURE_AGENT_TASK_ID: undefined,
+            ALLURE_AGENT_CONVERSATION_ID: undefined,
+        }, async () => await executeAllureRun({
+            allureReport,
+            knownIssues,
+            cwd,
+            command,
+            commandArgs,
+            environmentVariables: childEnvironmentVariables,
+            environment: resolvedEnvironment?.id,
+            withQualityGate: false,
+            logs: "pipe",
+            silent,
+            ignoreLogs: false,
+            logProcessExit: false,
+        }));
+        await persistLatestAgentState({
+            cwd,
+            outputDir,
+            expectationsPath,
+            command: commandString,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            status: "finished",
+            exitCode: globalExitCode.actual ?? globalExitCode.original,
+        });
+        exit(globalExitCode.actual ?? globalExitCode.original);
+    }
+    finally {
+        await rerunContext?.cleanup();
+    }
+};

package/dist/commands/commons/run.d.ts

@@ -0,0 +1,48 @@
+import { AllureReport } from "@allurereport/core";
+import { type KnownTestFailure } from "@allurereport/core-api";
+import type { ExitCode, QualityGateValidationResult } from "@allurereport/plugin-api";
+export type TestProcessResult = {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    qualityGateResults: QualityGateValidationResult[];
+};
+export type RunLogsMode = "pipe" | "inherit" | "ignore";
+export declare const executeNestedAllureCommand: (params: {
+    command: string;
+    commandArgs: string[];
+    cwd: string;
+    environmentVariables?: Record<string, string>;
+    silent?: boolean;
+}) => Promise<number | null>;
+export declare const runTests: (params: {
+    allureReport: AllureReport;
+    knownIssues: KnownTestFailure[];
+    cwd: string;
+    command: string;
+    commandArgs: string[];
+    environmentVariables: Record<string, string>;
+    environment?: string;
+    withQualityGate: boolean;
+    silent?: boolean;
+    logs?: RunLogsMode;
+    logProcessExit?: boolean;
+}) => Promise<TestProcessResult | null>;
+export declare const executeAllureRun: (params: {
+    allureReport: AllureReport;
+    knownIssues: KnownTestFailure[];
+    cwd: string;
+    command: string;
+    commandArgs: string[];
+    environmentVariables?: Record<string, string>;
+    environment?: string;
+    withQualityGate: boolean;
+    silent?: boolean;
+    logs?: RunLogsMode;
+    ignoreLogs?: boolean;
+    maxRerun?: number;
+    logProcessExit?: boolean;
+}) => Promise<{
+    globalExitCode: ExitCode;
+    testProcessResult: TestProcessResult | null;
+}>;