@rspack-debug/test-tools 1.3.14

package/dist/processor/hook.d.ts

@@ -0,0 +1,44 @@
+import { type TTestContextOptions, TestContext } from "../test/context";
+import type { ECompilerType, ITestContext, ITestEnv, TCompiler, TCompilerOptions } from "../type";
+import { type ISnapshotProcessorOptions, SnapshotProcessor } from "./snapshot";
+export declare class HookCasesContext extends TestContext {
+    protected src: string;
+    protected testName: string;
+    protected options: TTestContextOptions;
+    protected promises: Promise<void>[];
+    protected count: number;
+    protected snapshots: Record<string | number, Array<[string | Buffer, string]>>;
+    protected snapshotsList: Array<string | number>;
+    constructor(src: string, testName: string, options: TTestContextOptions);
+    /**
+     * Snapshot function arguments and return value.
+     * Generated snapshot is located in the same directory with the test source.
+     * @example
+     * compiler.hooks.compilation("name", context.snapped((...args) => { ... }))
+     */
+    snapped(cb: (...args: unknown[]) => Promise<unknown>, prefix?: string): (this: any, ...args: unknown[]) => Promise<unknown>;
+    /**
+     * @internal
+     */
+    _addSnapshot(content: unknown, name: string, group: string | number): void;
+    /**
+     * @internal
+     */
+    collectSnapshots(env: ITestEnv, options?: {
+        diff: {};
+    }): Promise<void>;
+}
+export interface IHookProcessorOptions<T extends ECompilerType> extends ISnapshotProcessorOptions<T> {
+    options?: (context: ITestContext) => TCompilerOptions<T>;
+    compiler?: (context: ITestContext, compiler: TCompiler<T>) => Promise<void>;
+    check?: (context: ITestContext) => Promise<void>;
+}
+export declare class HookTaskProcessor<T extends ECompilerType> extends SnapshotProcessor<T> {
+    protected _hookOptions: IHookProcessorOptions<T>;
+    constructor(_hookOptions: IHookProcessorOptions<T>);
+    config(context: ITestContext): Promise<void>;
+    compiler(context: ITestContext): Promise<void>;
+    check(env: ITestEnv, context: HookCasesContext): Promise<void>;
+    static defaultOptions<T extends ECompilerType>(context: ITestContext): TCompilerOptions<T>;
+    static overrideOptions<T extends ECompilerType>(options: TCompilerOptions<T>): void;
+}

package/dist/processor/hook.js

@@ -0,0 +1,204 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HookTaskProcessor = exports.HookCasesContext = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const core_1 = require("@rspack/core");
+const jest_snapshot_1 = require("jest-snapshot");
+const pretty_format_1 = require("pretty-format");
+const path_serializer_1 = require("path-serializer");
+const context_1 = require("../test/context");
+const snapshot_1 = require("./snapshot");
+const srcDir = node_path_1.default.resolve(__dirname, "../../tests/fixtures");
+const distDir = node_path_1.default.resolve(__dirname, "../../tests/js/hook");
+const sourceSerializer = {
+    test(val) {
+        return val instanceof core_1.sources.Source;
+    },
+    print(val) {
+        return val.source();
+    }
+};
+const internalSerializer = {
+    test(val) {
+        return val instanceof core_1.Compiler || val instanceof core_1.Compilation;
+    },
+    print(val) {
+        return JSON.stringify(`${val.constructor.name}(internal ignored)`);
+    }
+};
+const testPathSerializer = (0, path_serializer_1.createSnapshotSerializer)({
+    replace: [
+        {
+            match: srcDir,
+            mark: "<HOOK_SRC_DIR>"
+        },
+        {
+            match: distDir,
+            mark: "<HOOK_DIST_DIR>"
+        }
+    ]
+});
+const escapeRegex = true;
+const printFunctionName = false;
+const normalizeNewlines = (str) => str.replace(/\r\n|\r/g, "\n");
+const serialize = (val, indent = 2, formatOverrides = {}) => normalizeNewlines((0, pretty_format_1.format)(val, {
+    escapeRegex,
+    indent,
+    plugins: [
+        ...(0, jest_snapshot_1.getSerializers)(),
+        sourceSerializer,
+        internalSerializer,
+        testPathSerializer
+    ],
+    printFunctionName,
+    ...formatOverrides
+}));
+class HookCasesContext extends context_1.TestContext {
+    constructor(src, testName, options) {
+        super(options);
+        this.src = src;
+        this.testName = testName;
+        this.options = options;
+        this.promises = [];
+        this.count = 0;
+        this.snapshots = {};
+        this.snapshotsList = [];
+        this.snapped = this.snapped.bind(this);
+    }
+    /**
+     * Snapshot function arguments and return value.
+     * Generated snapshot is located in the same directory with the test source.
+     * @example
+     * compiler.hooks.compilation("name", context.snapped((...args) => { ... }))
+     */
+    snapped(cb, prefix = "") {
+        // eslint-disable-next-line
+        const context = this;
+        return function SNAPPED_HOOK(...args) {
+            const group = prefix ? prefix : context.count++;
+            context._addSnapshot(args, "input", group);
+            const output = cb.apply(this, args);
+            if (output && typeof output.then === "function") {
+                let resolve;
+                context.promises.push(new Promise(r => (resolve = r)));
+                return output
+                    .then((o) => {
+                    context._addSnapshot(o, "output (Promise resolved)", group);
+                    return o;
+                })
+                    .catch((o) => {
+                    context._addSnapshot(o, "output (Promise rejected)", group);
+                    return o;
+                })
+                    .finally(resolve);
+            }
+            context._addSnapshot(output, "output", group);
+            return output;
+        };
+    }
+    /**
+     * @internal
+     */
+    _addSnapshot(content, name, group) {
+        const normalizedContent = Buffer.isBuffer(content)
+            ? content
+            : serialize(content, undefined, {
+                escapeString: true,
+                printBasicPrototype: true
+            }).replace(/\r\n/g, "\n");
+        (this.snapshots[group] = this.snapshots[group] || []).push([
+            normalizedContent,
+            name
+        ]);
+        if (!this.snapshotsList.includes(group)) {
+            this.snapshotsList.push(group);
+        }
+    }
+    /**
+     * @internal
+     */
+    async collectSnapshots(env, options = {
+        diff: {}
+    }) {
+        await Promise.allSettled(this.promises);
+        if (!this.snapshotsList.length)
+            return;
+        const snapshots = this.snapshotsList.reduce((acc, group, index) => {
+            const block = this.snapshots[group || index].reduce((acc, [content, name]) => {
+                name = `## ${name || `test: ${index}`}\n\n`;
+                const block = `\`\`\`javascript\n${content}\n\`\`\`\n`;
+                return `${acc}${name + block}\n`;
+            }, "");
+            return `${acc}# ${Number.isInteger(group) ? `Group: ${index}` : group}\n\n${block}`;
+        }, "");
+        env
+            .expect(snapshots)
+            .toMatchFileSnapshot(node_path_1.default.join(this.src, "hooks.snap.txt"), options);
+    }
+}
+exports.HookCasesContext = HookCasesContext;
+class HookTaskProcessor extends snapshot_1.SnapshotProcessor {
+    constructor(_hookOptions) {
+        super({
+            defaultOptions: (HookTaskProcessor.defaultOptions),
+            ..._hookOptions
+        });
+        this._hookOptions = _hookOptions;
+    }
+    async config(context) {
+        await super.config(context);
+        const compiler = this.getCompiler(context);
+        if (typeof this._hookOptions.options === "function") {
+            compiler.mergeOptions(this._hookOptions.options(context));
+        }
+    }
+    async compiler(context) {
+        await super.compiler(context);
+        if (typeof this._hookOptions.compiler === "function") {
+            const compiler = this.getCompiler(context);
+            await this._hookOptions.compiler(context, compiler.getCompiler());
+        }
+    }
+    async check(env, context) {
+        await context.collectSnapshots(env);
+        await super.check(env, context);
+        if (typeof this._hookOptions.check === "function") {
+            await this._hookOptions.check(context);
+        }
+    }
+    static defaultOptions(context) {
+        return {
+            context: context.getSource(),
+            mode: "production",
+            target: "async-node",
+            devtool: false,
+            cache: false,
+            entry: "./hook",
+            output: {
+                path: context.getDist()
+            },
+            optimization: {
+                minimize: false
+            },
+            experiments: {
+                css: true,
+                rspackFuture: {
+                    bundlerInfo: {
+                        force: false
+                    }
+                }
+            }
+        };
+    }
+    static overrideOptions(options) {
+        if (!global.printLogger) {
+            options.infrastructureLogging = {
+                level: "error"
+            };
+        }
+    }
+}
+exports.HookTaskProcessor = HookTaskProcessor;

package/dist/processor/hot-new-incremental.d.ts

@@ -0,0 +1,14 @@
+import { ECompilerType, type ITestContext, type ITestEnv, type TCompilerOptions } from "../type";
+import type { IBasicProcessorOptions } from "./basic";
+import { HotProcessor } from "./hot";
+export interface IHotNewIncrementalProcessorOptions<T extends ECompilerType> extends Omit<IBasicProcessorOptions<T>, "runable"> {
+    target: TCompilerOptions<T>["target"];
+    webpackCases: boolean;
+}
+export declare class HotNewIncrementalProcessor<T extends ECompilerType> extends HotProcessor<T> {
+    protected _hotOptions: IHotNewIncrementalProcessorOptions<T>;
+    constructor(_hotOptions: IHotNewIncrementalProcessorOptions<T>);
+    run(env: ITestEnv, context: ITestContext): Promise<void>;
+    afterAll(context: ITestContext): Promise<void>;
+    static defaultOptions<T extends ECompilerType>(this: HotNewIncrementalProcessor<T>, context: ITestContext): TCompilerOptions<T>;
+}

package/dist/processor/hot-new-incremental.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotNewIncrementalProcessor = void 0;
+const type_1 = require("../type");
+const hot_1 = require("./hot");
+class HotNewIncrementalProcessor extends hot_1.HotProcessor {
+    constructor(_hotOptions) {
+        super({
+            defaultOptions: HotNewIncrementalProcessor.defaultOptions,
+            ..._hotOptions
+        });
+        this._hotOptions = _hotOptions;
+    }
+    async run(env, context) {
+        context.setValue(this._options.name, "documentType", this._hotOptions.webpackCases ? type_1.EDocumentType.Fake : type_1.EDocumentType.JSDOM);
+        await super.run(env, context);
+    }
+    async afterAll(context) {
+        try {
+            await super.afterAll(context);
+        }
+        catch (e) {
+            const isFake = context.getValue(this._options.name, "documentType") ===
+                type_1.EDocumentType.Fake;
+            if (isFake && /Should run all hot steps/.test(e.message))
+                return;
+            throw e;
+        }
+    }
+    static defaultOptions(context) {
+        const options = super.defaultOptions(context);
+        if (this._hotOptions.compilerType === type_1.ECompilerType.Rspack) {
+            const rspackOptions = options;
+            rspackOptions.experiments ??= {};
+            rspackOptions.experiments.incremental ??= "advance-silent";
+        }
+        else {
+            throw new Error("HotNewIncrementalProcessor should only used for Rspack.");
+        }
+        return options;
+    }
+}
+exports.HotNewIncrementalProcessor = HotNewIncrementalProcessor;

package/dist/processor/hot-step.d.ts

@@ -0,0 +1,18 @@
+import type { THotStepRuntimeData } from "../runner";
+import type { ECompilerType, ITestContext, ITestEnv, TCompilerOptions, TCompilerStatsCompilation } from "../type";
+import { HotProcessor, type IHotProcessorOptions } from "./hot";
+type TModuleGetHandler = (file: string, options: TCompilerOptions<ECompilerType>) => string[];
+export interface IHotSnapshotProcessorOptions<T extends ECompilerType> extends IHotProcessorOptions<T> {
+    getModuleHandler?: TModuleGetHandler;
+    snapshot?: string;
+}
+export declare class HotSnapshotProcessor<T extends ECompilerType> extends HotProcessor<T> {
+    protected _hotOptions: IHotSnapshotProcessorOptions<T>;
+    private hashes;
+    private entries;
+    constructor(_hotOptions: IHotSnapshotProcessorOptions<T>);
+    run(env: ITestEnv, context: ITestContext): Promise<void>;
+    check(env: ITestEnv, context: ITestContext): Promise<void>;
+    protected matchStepSnapshot(env: ITestEnv, context: ITestContext, step: number, stats: TCompilerStatsCompilation<T>, runtime?: THotStepRuntimeData): void;
+}
+export {};

package/dist/processor/hot-step.js

@@ -0,0 +1,299 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotSnapshotProcessor = void 0;
+const node_path_1 = __importDefault(require("node:path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const placeholder_1 = require("../helper/expect/placeholder");
+const win_1 = require("../helper/win");
+const hot_1 = require("./hot");
+const NOOP_SET = new Set();
+const escapeLocalName = (str) => str.split(/[-<>:"/|?*.]/).join("_");
+const SELF_HANDLER = (file, options) => {
+    let res = [];
+    const hotUpdateGlobal = (_, modules) => {
+        res = Object.keys(modules);
+    };
+    const hotUpdateGlobalKey = escapeLocalName(`${options.output?.hotUpdateGlobal || "webpackHotUpdate"}${options.output?.uniqueName || ""}`);
+    global.self ??= {};
+    global.self[hotUpdateGlobalKey] = hotUpdateGlobal;
+    require(file);
+    delete global.self[hotUpdateGlobalKey];
+    if (!Object.keys(global.self).length) {
+        delete global.self;
+    }
+    return res;
+};
+const NODE_HANDLER = (file) => {
+    return Object.keys(require(file).modules) || [];
+};
+const GET_MODULE_HANDLER = {
+    web: SELF_HANDLER,
+    webworker: SELF_HANDLER,
+    "async-node": NODE_HANDLER,
+    node: NODE_HANDLER
+};
+class HotSnapshotProcessor extends hot_1.HotProcessor {
+    constructor(_hotOptions) {
+        super(_hotOptions);
+        this._hotOptions = _hotOptions;
+        this.hashes = [];
+        this.entries = {};
+    }
+    async run(env, context) {
+        context.setValue(this._options.name, "hotUpdateStepChecker", (hotUpdateContext, stats, runtime) => {
+            const statsJson = stats.toJson({
+                assets: true,
+                chunks: true
+            });
+            const chunks = Array.from(
+            // Some chunk fields are missing from rspack
+            stats?.compilation.chunks || NOOP_SET);
+            for (const entry of chunks.filter(i => i.hasRuntime())) {
+                if (!this.entries[entry.id] && entry.runtime) {
+                    this.entries[entry.id] =
+                        // Webpack uses `string | SortableSet<string>` for `entry.runtime`
+                        typeof entry.runtime === "string"
+                            ? [entry.runtime]
+                            : Array.from(entry.runtime);
+                }
+            }
+            this.matchStepSnapshot(env, context, hotUpdateContext.updateIndex, statsJson, runtime);
+            this.hashes.push(stats.hash);
+        });
+        context.setValue(this._options.name, "hotUpdateStepErrorChecker", (_, stats, runtime) => {
+            this.hashes.push(stats.hash);
+        });
+        await super.run(env, context);
+    }
+    async check(env, context) {
+        const compiler = this.getCompiler(context);
+        const stats = compiler.getStats();
+        if (!stats || !stats.hash) {
+            env.expect(false);
+            return;
+        }
+        const statsJson = stats.toJson({ assets: true, chunks: true });
+        const chunks = Array.from(
+        // Some chunk fields are missing from rspack
+        stats?.compilation.chunks || NOOP_SET);
+        for (const entry of chunks.filter(i => i.hasRuntime())) {
+            if (entry.runtime) {
+                this.entries[entry.id] =
+                    // Webpack uses `string | SortableSet<string>` for `entry.runtime`
+                    typeof entry.runtime === "string"
+                        ? [entry.runtime]
+                        : Array.from(entry.runtime);
+            }
+        }
+        let matchFailed = null;
+        try {
+            this.matchStepSnapshot(env, context, 0, statsJson);
+        }
+        catch (e) {
+            matchFailed = e;
+        }
+        this.hashes.push(stats.hash);
+        if (matchFailed) {
+            throw matchFailed;
+        }
+    }
+    matchStepSnapshot(env, context, step, stats, runtime) {
+        const compiler = this.getCompiler(context);
+        const compilerOptions = compiler.getOptions();
+        const getModuleHandler = this._hotOptions.getModuleHandler ||
+            GET_MODULE_HANDLER[compilerOptions.target];
+        env.expect(typeof getModuleHandler).toBe("function");
+        const lastHash = this.hashes[this.hashes.length - 1];
+        const snapshotPath = context.getSource(`${this._hotOptions.snapshot || `__snapshots__/${compilerOptions.target}`}/${step}.snap.txt`);
+        const title = `Case ${node_path_1.default.basename(this._options.name)}: Step ${step}`;
+        const hotUpdateFile = [];
+        const hotUpdateManifest = [];
+        const changedFiles = this.updateOptions.updateIndex === 0
+            ? []
+            : this.updateOptions.changedFiles.map((i) => (0, win_1.escapeSep)(node_path_1.default.relative(context.getSource(), i)));
+        changedFiles.sort();
+        const hashes = {
+            [lastHash || "LAST_HASH"]: "LAST_HASH",
+            [stats.hash]: "CURRENT_HASH"
+        };
+        // TODO: find a better way
+        // replace [runtime] to [runtime of id] to prevent worker hash
+        const runtimes = {};
+        for (const [id, runtime] of Object.entries(this.entries)) {
+            if (typeof runtime === "string") {
+                if (runtime !== id) {
+                    runtimes[runtime] = `[runtime of ${id}]`;
+                }
+            }
+            else if (Array.isArray(runtime)) {
+                for (const r of runtime) {
+                    if (r !== id) {
+                        runtimes[r] = `[runtime of ${id}]`;
+                    }
+                }
+            }
+        }
+        const replaceContent = (str) => {
+            return (0, placeholder_1.normalizePlaceholder)(Object.entries(hashes)
+                .reduce((str, [raw, replacement]) => {
+                return str.split(raw).join(replacement);
+            }, str)
+                .replace(/\/\/ (\d+)\s+(?=var cssReload)/, ""));
+        };
+        const replaceFileName = (str) => {
+            return Object.entries({
+                ...hashes,
+                ...runtimes
+            }).reduce((str, [raw, replacement]) => {
+                return str.split(raw).join(replacement);
+            }, str);
+        };
+        const fileList = stats
+            .assets.map(i => {
+            const fileName = i.name;
+            const renderName = replaceFileName(fileName);
+            const content = replaceContent(fs_extra_1.default.readFileSync(context.getDist(fileName), "utf-8"));
+            if (fileName.endsWith("hot-update.js")) {
+                const modules = getModuleHandler(context.getDist(fileName), compilerOptions);
+                const runtime = [];
+                for (const i of content.matchAll(/\/\/ (webpack\/runtime\/[\w_-]+)\s*\n/g)) {
+                    runtime.push(i[1]);
+                }
+                modules.sort();
+                runtime.sort();
+                hotUpdateFile.push({
+                    name: renderName,
+                    content,
+                    modules,
+                    runtime
+                });
+                return `- Update: ${renderName}, size: ${content.length}`;
+            }
+            if (fileName.endsWith("hot-update.json")) {
+                const manifest = JSON.parse(content);
+                manifest.c?.sort();
+                manifest.r?.sort();
+                manifest.m?.sort();
+                hotUpdateManifest.push({
+                    name: renderName,
+                    content: JSON.stringify(manifest)
+                });
+                return `- Manifest: ${renderName}, size: ${i.size}`;
+            }
+            if (fileName.endsWith(".js")) {
+                return `- Bundle: ${renderName}`;
+            }
+        })
+            .filter(Boolean);
+        fileList.sort();
+        hotUpdateManifest.sort((a, b) => (a.name > b.name ? 1 : -1));
+        hotUpdateFile.sort((a, b) => (a.name > b.name ? 1 : -1));
+        if (runtime?.javascript) {
+            runtime.javascript.outdatedModules.sort();
+            runtime.javascript.updatedModules.sort();
+            runtime.javascript.updatedRuntime.sort();
+            runtime.javascript.acceptedModules.sort();
+            runtime.javascript.disposedModules.sort();
+            for (const value of Object.values(runtime.javascript.outdatedDependencies)) {
+                value.sort();
+            }
+        }
+        const content = `
+# ${title}
+
+## Changed Files
+${changedFiles.map(i => `- ${i}`).join("\n")}
+
+## Asset Files
+${fileList.join("\n")}
+
+## Manifest
+${hotUpdateManifest
+            .map(i => `
+### ${i.name}
+
+\`\`\`json
+${i.content}
+\`\`\`
+`)
+            .join("\n\n")}
+
+## Update
+
+${hotUpdateFile
+            .map(i => `
+### ${i.name}
+
+#### Changed Modules
+${i.modules.map(i => `- ${i}`).join("\n")}
+
+#### Changed Runtime Modules
+${i.runtime.map(i => `- ${i}`).join("\n")}
+
+#### Changed Content
+\`\`\`js
+${i.content}
+\`\`\`
+`)
+            .join("\n\n")}
+
+
+${runtime
+            ? `
+## Runtime
+### Status
+
+\`\`\`txt
+${runtime.statusPath.join(" => ")}
+\`\`\`
+
+${runtime.javascript
+                ? `
+
+### JavaScript
+
+#### Outdated
+
+Outdated Modules:
+${runtime.javascript.outdatedModules.map(i => `- ${i}`).join("\n")}
+
+
+Outdated Dependencies:
+\`\`\`json
+${JSON.stringify(runtime.javascript.outdatedDependencies || {}, null, 2)}
+\`\`\`
+
+#### Updated
+
+Updated Modules:
+${runtime.javascript.updatedModules.map(i => `- ${i}`).join("\n")}
+
+Updated Runtime:
+${runtime.javascript.updatedRuntime.map(i => `- \`${i}\``).join("\n")}
+
+
+#### Callback
+
+Accepted Callback:
+${runtime.javascript.acceptedModules.map(i => `- ${i}`).join("\n")}
+
+Disposed Callback:
+${runtime.javascript.disposedModules.map(i => `- ${i}`).join("\n")}
+`
+                : ""}
+
+`
+            : ""}
+
+				`
+            .replaceAll(/%3A(\d+)%2F/g, (match, capture) => {
+            return match.replace(capture, "PORT");
+        })
+            .trim();
+        env.expect(content).toMatchFileSnapshot(snapshotPath);
+    }
+}
+exports.HotSnapshotProcessor = HotSnapshotProcessor;

package/dist/processor/hot.d.ts

@@ -0,0 +1,17 @@
+import { ECompilerType, type ITestContext, type ITestEnv, type ITestRunner, type TCompilerOptions, type TUpdateOptions } from "../type";
+import { BasicProcessor, type IBasicProcessorOptions } from "./basic";
+export interface IHotProcessorOptions<T extends ECompilerType> extends Omit<IBasicProcessorOptions<T>, "runable"> {
+    target: TCompilerOptions<T>["target"];
+    checkSteps?: boolean;
+}
+export declare class HotProcessor<T extends ECompilerType> extends BasicProcessor<T> {
+    protected _hotOptions: IHotProcessorOptions<T>;
+    protected updateOptions: TUpdateOptions;
+    protected runner: ITestRunner | null;
+    constructor(_hotOptions: IHotProcessorOptions<T>);
+    run(env: ITestEnv, context: ITestContext): Promise<void>;
+    static findBundle<T extends ECompilerType>(this: HotProcessor<T>, context: ITestContext): string[];
+    afterAll(context: ITestContext): Promise<void>;
+    static defaultOptions<T extends ECompilerType>(this: HotProcessor<T>, context: ITestContext): TCompilerOptions<T>;
+    static overrideOptions<T extends ECompilerType>(this: HotProcessor<T>, context: ITestContext, options: TCompilerOptions<T>): void;
+}