@allurereport/plugin-api 3.0.0-beta.10

package/README.md

@@ -0,0 +1,27 @@
+# Plugin API
+
+> Collection of interfaces for Allure plugins
+
+[<img src="https://allurereport.org/public/img/allure-report.svg" height="85px" alt="Allure Report logo" align="right" />](https://allurereport.org "Allure Report")
+
+- Learn more about Allure Report at https://allurereport.org
+- 📚 [Documentation](https://allurereport.org/docs/) – discover official documentation for Allure Report
+- ❓ [Questions and Support](https://github.com/orgs/allure-framework/discussions/categories/questions-support) – get help from the team and community
+- 📢 [Official announcements](https://github.com/orgs/allure-framework/discussions/categories/announcements) – be in touch with the latest updates
+- 💬 [General Discussion ](https://github.com/orgs/allure-framework/discussions/categories/general-discussion) – engage in casual conversations, share insights and ideas with the community
+
+---
+
+## Overview
+
+The interfaces in the package describe the entities used for building Allure Plugins.
+
+## Install
+
+Use your favorite package manager to install the package:
+
+```shell
+npm add @allurereport/plugin-api
+yarn add @allurereport/plugin-api
+pnpm add @allurereport/plugin-api
+```

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+import type { DefaultLabelsConfig, EnvironmentsConfig, ReportVariables } from "@allurereport/core-api";
+import type { PluginDescriptor } from "./plugin.js";
+import type { QualityGateConfig } from "./qualityGate.js";
+export interface Config {
+    name?: string;
+    output?: string;
+    historyPath?: string;
+    knownIssuesPath?: string;
+    defaultLabels?: DefaultLabelsConfig;
+    environments?: EnvironmentsConfig;
+    variables?: ReportVariables;
+    plugins?: Record<string, PluginDescriptor>;
+    qualityGate?: QualityGateConfig;
+}
+export declare const defineConfig: (allureConfig: Config) => Config;

package/dist/config.js

@@ -0,0 +1,3 @@
+export const defineConfig = (allureConfig) => {
+    return allureConfig;
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./config.js";
+export type * from "./plugin.js";
+export type * from "./qualityGate.js";
+export type * from "./store.js";
+export type * from "./resultFile.js";
+export * from "./utils/misc.js";
+export * from "./utils/tree.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./config.js";
+export * from "./utils/misc.js";
+export * from "./utils/tree.js";

package/dist/plugin.d.ts

@@ -0,0 +1,34 @@
+import type { AllureStore } from "./store.js";
+export interface PluginDescriptor {
+    import?: string;
+    enabled?: boolean;
+    options?: Record<string, any>;
+}
+export interface ReportFiles {
+    addFile(path: string, data: Buffer): Promise<void>;
+}
+export interface PluginState {
+    set(key: string, value: any): Promise<void>;
+    get(key: string): Promise<void>;
+    unset(key: string): Promise<void>;
+}
+export interface PluginContext {
+    state: PluginState;
+    allureVersion: string;
+    reportUuid: string;
+    reportName: string;
+    reportFiles: ReportFiles;
+}
+export interface BatchOptions {
+    maxTimeout?: number;
+}
+export interface Realtime {
+    onTestResults(listener: (trIds: string[]) => Promise<void>, options?: BatchOptions): void;
+    onTestFixtureResults(listener: (tfrIds: string[]) => Promise<void>, options?: BatchOptions): void;
+    onAttachmentFiles(listener: (afIds: string[]) => Promise<void>, options?: BatchOptions): void;
+}
+export interface Plugin {
+    start?(context: PluginContext, store: AllureStore, realtime: Realtime): Promise<void>;
+    update?(context: PluginContext, store: AllureStore): Promise<void>;
+    done?(context: PluginContext, store: AllureStore): Promise<void>;
+}

package/dist/plugin.js

@@ -0,0 +1 @@
+export {};

package/dist/qualityGate.d.ts

@@ -0,0 +1,44 @@
+import type { AllureStore } from "./store.js";
+export type QualityGateRules = Record<string, any>;
+export type QualityGateRulesBaseMeta<T> = {
+    type: T;
+};
+export type QualityGateLabelsRulesMeta = QualityGateRulesBaseMeta<"label"> & {
+    name: string;
+    value: string;
+};
+export type QualityGateParametersRulesMeta = QualityGateRulesBaseMeta<"parameter"> & {
+    name: string;
+    value: string;
+};
+export type QualityGateLabelsEnforceConfig = {
+    type: "label";
+    name: string;
+    value: string;
+    rules: QualityGateRules;
+};
+export type QualityGateParametersEnforceConfig = {
+    type: "parameter";
+    name: string;
+    value: string;
+    rules: QualityGateRules;
+};
+export type QualityGateRulesMeta = Omit<QualityGateLabelsRulesMeta, "rules"> | Omit<QualityGateParametersRulesMeta, "rules">;
+export type QualityGateEnforceConfig = QualityGateLabelsEnforceConfig | QualityGateParametersEnforceConfig;
+export type QualityGateValidationResult = {
+    success: boolean;
+    rule: string;
+    meta?: QualityGateRulesMeta;
+    expected?: number;
+    actual?: number;
+    message?: string;
+};
+export interface QualityGateValidator {
+    validate(store: AllureStore): Promise<QualityGateValidationResult>;
+}
+export type QualityGateValidatorConstructor = new (limit: number, meta?: QualityGateRulesMeta) => QualityGateValidator;
+export type QualityGateConfig = {
+    rules?: QualityGateRules;
+    enforce?: QualityGateEnforceConfig[];
+    validators?: Record<string, QualityGateValidatorConstructor>;
+};

package/dist/qualityGate.js

@@ -0,0 +1 @@
+export {};

package/dist/resultFile.d.ts

@@ -0,0 +1,12 @@
+import type { Readable } from "node:stream";
+export interface ResultFile {
+    readContent: <T>(transform: (stream: Readable) => Promise<T | undefined>) => Promise<T | undefined>;
+    getOriginalFileName: () => string;
+    getExtension: () => string;
+    getContentType: () => string | undefined;
+    getContentLength: () => number | undefined;
+    asJson: <T>() => Promise<T | undefined>;
+    asUtf8String: () => Promise<string | undefined>;
+    asBuffer: () => Promise<Buffer | undefined>;
+    writeTo: (path: string) => Promise<void>;
+}

package/dist/resultFile.js

@@ -0,0 +1 @@
+export {};

package/dist/store.d.ts

@@ -0,0 +1,32 @@
+import type { AttachmentLink, HistoryDataPoint, HistoryTestResult, KnownTestFailure, Statistic, TestCase, TestFixtureResult, TestResult } from "@allurereport/core-api";
+import type { ResultFile } from "./resultFile.js";
+export interface AllureStore {
+    allTestCases: () => Promise<TestCase[]>;
+    allTestResults: (options?: {
+        includeHidden: boolean;
+    }) => Promise<TestResult[]>;
+    allAttachments: () => Promise<AttachmentLink[]>;
+    allMetadata: () => Promise<Record<string, any>>;
+    allFixtures: () => Promise<TestFixtureResult[]>;
+    allHistoryDataPoints: () => Promise<HistoryDataPoint[]>;
+    allKnownIssues: () => Promise<KnownTestFailure[]>;
+    testCaseById: (tcId: string) => Promise<TestCase | undefined>;
+    testResultById: (trId: string) => Promise<TestResult | undefined>;
+    attachmentById: (attachmentId: string) => Promise<AttachmentLink | undefined>;
+    attachmentContentById: (attachmentId: string) => Promise<ResultFile | undefined>;
+    metadataByKey: <T>(key: string) => Promise<T | undefined>;
+    testResultsByTcId: (tcId: string) => Promise<TestResult[]>;
+    attachmentsByTrId: (trId: string) => Promise<AttachmentLink[]>;
+    retriesByTrId: (trId: string) => Promise<TestResult[]>;
+    historyByTrId: (trId: string) => Promise<HistoryTestResult[]>;
+    fixturesByTrId: (trId: string) => Promise<TestFixtureResult[]>;
+    failedTestResults: () => Promise<TestResult[]>;
+    unknownFailedTestResults: () => Promise<TestResult[]>;
+    testResultsByLabel: (labelName: string) => Promise<{
+        _: TestResult[];
+        [x: string]: TestResult[];
+    }>;
+    testsStatistic: (filter?: (testResult: TestResult) => boolean) => Promise<Statistic>;
+    allEnvironments: () => Promise<string[]>;
+    testResultsByEnvironment: (env: string) => Promise<TestResult[]>;
+}

package/dist/store.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/misc.d.ts

@@ -0,0 +1 @@
+export declare const md5: (data: string) => string;

package/dist/utils/misc.js

@@ -0,0 +1,2 @@
+import { createHash } from "node:crypto";
+export const md5 = (data) => createHash("md5").update(data).digest("hex");

package/dist/utils/tree.d.ts

@@ -0,0 +1,10 @@
+import { type Comparator, type DefaultTreeGroup, type DefaultTreeLeaf, type TestResult, type TreeData, type TreeGroup, type TreeLeaf } from "@allurereport/core-api";
+export declare const byLabels: (item: TestResult, labelNames: string[]) => string[][];
+export declare const filterTreeLabels: (data: TestResult[], labelNames: string[]) => string[];
+export declare const createTreeByLabels: <T = TestResult, L = DefaultTreeLeaf, G = DefaultTreeGroup>(data: T[], labelNames: string[], leafFactory?: (item: T) => TreeLeaf<L>, groupFactory?: (parentGroup: string | undefined, groupClassifier: string) => TreeGroup<G>, addLeafToGroup?: (group: TreeGroup<G>, leaf: TreeLeaf<L>) => void) => TreeData<L, G>;
+export declare const createTreeByCategories: <T = TestResult, L = DefaultTreeLeaf, G = DefaultTreeGroup>(data: T[], leafFactory?: (item: T) => TreeLeaf<L>, groupFactory?: (parentGroup: string | undefined, groupClassifier: string) => TreeGroup<G>, addLeafToGroup?: (group: TreeGroup<G>, leaf: TreeLeaf<L>) => void) => TreeData<L, G>;
+export declare const byCategories: (item: TestResult) => string[][];
+export declare const preciseTreeLabels: <T = TestResult>(labelNames: string[], trs: T[], labelNamesAccessor?: (tr: T) => string[]) => string[];
+export declare const filterTree: <L, G>(tree: TreeData<L, G>, predicate: (leaf: TreeLeaf<L>) => boolean) => TreeData<L, G>;
+export declare const sortTree: <L, G>(tree: TreeData<L, G>, comparator: Comparator<TreeLeaf<L>>) => TreeData<L, G>;
+export declare const transformTree: <L, G>(tree: TreeData<L, G>, transformer: (leaf: TreeLeaf<L>, idx: number) => TreeLeaf<L>) => TreeData<L, G>;

package/dist/utils/tree.js

@@ -0,0 +1,199 @@
+import { findByLabelName, } from "@allurereport/core-api";
+import { emptyStatistic } from "@allurereport/core-api";
+import { md5 } from "./misc.js";
+const addLeaf = (node, nodeId) => {
+    if (node.leaves === undefined) {
+        node.leaves = [];
+    }
+    if (node.leaves.find((value) => value === nodeId)) {
+        return;
+    }
+    node.leaves.push(nodeId);
+};
+const addGroup = (node, nodeId) => {
+    if (node.groups === undefined) {
+        node.groups = [];
+    }
+    if (node.groups.find((value) => value === nodeId)) {
+        return;
+    }
+    node.groups.push(nodeId);
+};
+const createTree = (data, classifier, leafFactory, groupFactory, addLeafToGroup = () => { }) => {
+    const groupsByClassifier = {};
+    const leavesById = {};
+    const groupsById = {};
+    const root = { groups: [], leaves: [] };
+    for (const item of data) {
+        const leaf = leafFactory(item);
+        leavesById[leaf.nodeId] = leaf;
+        const itemGroups = classifier(item);
+        let parentGroups = [root];
+        for (const layer of itemGroups) {
+            if (layer.length === 0) {
+                break;
+            }
+            parentGroups = layer.flatMap((group) => {
+                return parentGroups.map((parentGroup) => {
+                    const parentId = "nodeId" in parentGroup ? parentGroup.nodeId : "";
+                    if (groupsByClassifier[parentId] === undefined) {
+                        groupsByClassifier[parentId] = {};
+                    }
+                    if (groupsByClassifier[parentId][group] === undefined) {
+                        const newGroup = groupFactory(parentId, group);
+                        groupsByClassifier[parentId][group] = newGroup;
+                        groupsById[newGroup.nodeId] = newGroup;
+                    }
+                    const currentGroup = groupsByClassifier[parentId][group];
+                    addGroup(parentGroup, currentGroup.nodeId);
+                    addLeafToGroup(currentGroup, leaf);
+                    return currentGroup;
+                });
+            });
+        }
+        parentGroups.forEach((parentGroup) => addLeaf(parentGroup, leaf.nodeId));
+    }
+    return {
+        root,
+        groupsById,
+        leavesById,
+    };
+};
+export const byLabels = (item, labelNames) => {
+    return labelNames.map((labelName) => item.labels.filter((label) => labelName === label.name).map((label) => label.value ?? "__unknown") ?? []);
+};
+export const filterTreeLabels = (data, labelNames) => {
+    return [...labelNames]
+        .reverse()
+        .filter((labelName) => data.find((item) => findByLabelName(item.labels, labelName)))
+        .reverse();
+};
+export const createTreeByLabels = (data, labelNames, leafFactory, groupFactory, addLeafToGroup = () => { }) => {
+    const leafFactoryFn = leafFactory ??
+        ((tr) => {
+            const { id, name, status, duration } = tr;
+            return {
+                nodeId: id,
+                name,
+                status,
+                duration,
+            };
+        });
+    const groupFactoryFn = groupFactory ??
+        ((parentId, groupClassifier) => ({
+            nodeId: md5((parentId ? `${parentId}.` : "") + groupClassifier),
+            name: groupClassifier,
+            statistic: emptyStatistic(),
+        }));
+    return createTree(data, (item) => byLabels(item, labelNames), leafFactoryFn, groupFactoryFn, addLeafToGroup);
+};
+export const createTreeByCategories = (data, leafFactory, groupFactory, addLeafToGroup = () => { }) => {
+    const leafFactoryFn = leafFactory ??
+        ((tr) => {
+            const { id, name, status, duration } = tr;
+            return {
+                nodeId: id,
+                name,
+                status,
+                duration,
+            };
+        });
+    const groupFactoryFn = groupFactory ??
+        ((parentId, groupClassifier) => ({
+            nodeId: md5((parentId ? `${parentId}.` : "") + groupClassifier),
+            name: groupClassifier,
+            statistic: emptyStatistic(),
+        }));
+    return createTree(data, (item) => byCategories(item), leafFactoryFn, groupFactoryFn, addLeafToGroup);
+};
+export const byCategories = (item) => {
+    return [item.categories?.map((category) => category.name)];
+};
+export const preciseTreeLabels = (labelNames, trs, labelNamesAccessor = (tr) => tr.labels.map(({ name }) => name)) => {
+    const result = new Set();
+    for (const labelName of labelNames) {
+        if (trs.some((tr) => labelNamesAccessor(tr).includes(labelName))) {
+            result.add(labelName);
+        }
+    }
+    return Array.from(result);
+};
+export const filterTree = (tree, predicate) => {
+    const visitedGroups = new Set();
+    const { root, leavesById, groupsById } = tree;
+    const filterGroupLeaves = (group) => {
+        if (!predicate) {
+            return group;
+        }
+        if (group.groups?.length) {
+            group.groups.forEach((groupId) => {
+                const subGroup = groupsById[groupId];
+                if (!subGroup || visitedGroups.has(groupId)) {
+                    return;
+                }
+                filterGroupLeaves(subGroup);
+                visitedGroups.add(groupId);
+            });
+        }
+        if (group.leaves?.length) {
+            group.leaves = group.leaves.filter((leaveId) => predicate(leavesById[leaveId]));
+        }
+        return group;
+    };
+    filterGroupLeaves(root);
+    return tree;
+};
+export const sortTree = (tree, comparator) => {
+    const visitedGroups = new Set();
+    const { root, leavesById, groupsById } = tree;
+    const sortGroupLeaves = (group) => {
+        if (!comparator) {
+            return group;
+        }
+        if (group.groups?.length) {
+            group.groups.forEach((groupId) => {
+                if (visitedGroups.has(groupId)) {
+                    return;
+                }
+                sortGroupLeaves(groupsById[groupId]);
+                visitedGroups.add(groupId);
+            });
+        }
+        if (group.leaves?.length) {
+            group.leaves = group.leaves.sort((a, b) => {
+                const leafA = leavesById[a];
+                const leafB = leavesById[b];
+                return comparator(leafA, leafB);
+            });
+        }
+        return group;
+    };
+    sortGroupLeaves(root);
+    return tree;
+};
+export const transformTree = (tree, transformer) => {
+    const visitedGroups = new Set();
+    const { root, leavesById, groupsById } = tree;
+    const transformGroupLeaves = (group) => {
+        if (!transformer) {
+            return group;
+        }
+        if (group.groups?.length) {
+            group.groups.forEach((groupId) => {
+                if (visitedGroups.has(groupId)) {
+                    return;
+                }
+                transformGroupLeaves(groupsById[groupId]);
+                visitedGroups.add(groupId);
+            });
+        }
+        if (group.leaves?.length) {
+            group.leaves.forEach((leaf, i) => {
+                leavesById[leaf] = transformer(leavesById[leaf], i);
+            });
+        }
+        return group;
+    };
+    transformGroupLeaves(root);
+    return tree;
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@allurereport/plugin-api",
+  "version": "3.0.0-beta.10",
+  "description": "Allure Plugin API",
+  "keywords": [
+    "allure"
+  ],
+  "repository": "https://github.com/allure-framework/allure3",
+  "license": "Apache-2.0",
+  "author": "Qameta Software",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "run clean && tsc --project ./tsconfig.json",
+    "clean": "rimraf ./dist",
+    "eslint": "eslint ./src/**/*.{js,jsx,ts,tsx}",
+    "eslint:format": "eslint --fix ./src/**/*.{js,jsx,ts,tsx}",
+    "test": "rimraf ./out && vitest run"
+  },
+  "dependencies": {
+    "@allurereport/core-api": "3.0.0-beta.10"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^2.6.1",
+    "@types/eslint": "^8.56.11",
+    "@types/node": "^20.17.9",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/runner": "^2.1.8",
+    "@vitest/snapshot": "^2.1.8",
+    "allure-vitest": "^3.0.9",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsdoc": "^50.0.0",
+    "eslint-plugin-n": "^17.10.1",
+    "eslint-plugin-no-null": "^1.0.2",
+    "eslint-plugin-prefer-arrow": "^1.2.3",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}