@allurereport/plugin-api 3.0.0-beta.3

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,11 @@
+import type { PluginDescriptor } from "./plugin.js";
+import type { QualityGateConfig } from "./qualityGate.js";
+export interface Config {
+    name?: string;
+    output?: string;
+    historyPath?: string;
+    knownIssuesPath?: string;
+    qualityGate?: QualityGateConfig;
+    plugins?: Record<string, PluginDescriptor>;
+}
+export declare const defineConfig: (allureConfig: Config) => Promise<Config>;

package/dist/config.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/plugin.d.ts

@@ -0,0 +1,34 @@
+import { 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 "node:fs/promises";
+import { Readable } from "node:stream";
+export interface ResultFile {
+    readContent: <T>(transform: (stream: Readable) => Promise<T | undefined>) => Promise<T | undefined>;
+    getOriginalFileName: () => 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 @@
+import "node:fs/promises";

package/dist/store.d.ts

@@ -0,0 +1,30 @@
+import type { AttachmentLink, HistoryDataPoint, HistoryTestResult, KnownTestFailure, Statistic, TestCase, TestFixtureResult, TestResult } from "@allurereport/core-api";
+import { 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>;
+}

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,2 @@
+import type { DefaultTreeGroup, DefaultTreeLeaf, TestResult, TreeData } from "@allurereport/core-api";
+export declare const createTreeByLabels: (data: TestResult[], labelNames: string[]) => TreeData<DefaultTreeLeaf, DefaultTreeGroup>;

package/dist/utils/tree.js

@@ -0,0 +1,78 @@
+import { emptyStatistic, incrementStatistic } 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,
+    };
+};
+const byLabels = (item, labelNames) => {
+    return labelNames.map((labelName) => item.labels.filter((label) => labelName === label.name).map((label) => label.value ?? "__unknown") ?? []);
+};
+export const createTreeByLabels = (data, labelNames) => {
+    return createTree(data, (item) => byLabels(item, labelNames), ({ id, name, status, duration, flaky, retries }) => ({
+        nodeId: id,
+        name,
+        status,
+        duration,
+        flaky,
+    }), (parentId, groupClassifier) => ({
+        nodeId: md5((parentId ? `${parentId}.` : "") + groupClassifier),
+        name: groupClassifier,
+        statistic: emptyStatistic(),
+    }), (group, leaf) => {
+        incrementStatistic(group.statistic, leaf.status);
+    });
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@allurereport/plugin-api",
+  "version": "3.0.0-beta.3",
+  "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",
+    "test": "rimraf ./out && vitest run"
+  },
+  "dependencies": {
+    "@allurereport/core-api": "3.0.0-beta.3"
+  },
+  "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",
+    "allure-vitest": "^3.0.7",
+    "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"
+  }
+}