@thefehr/foundry-playwright 0.2.1

package/dist/cli/init.js

@@ -0,0 +1,129 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Action for the 'init' CLI command.
+ * Bootstraps a new Foundry E2E test project.
+ */
+export async function initAction() {
+    console.log("🚀 Initializing foundry-playwright project...");
+    const packageJsonPath = path.join(process.cwd(), "package.json");
+    if (!fs.existsSync(packageJsonPath)) {
+        console.error("❌ package.json not found. Please run this in a Node.js project root.");
+        process.exit(1);
+    }
+    // 1. Update package.json scripts
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    packageJson.scripts = packageJson.scripts || {};
+    const testCommand = "foundry-playwright test --docker";
+    if (!packageJson.scripts["test:e2e"]) {
+        packageJson.scripts["test:e2e"] = testCommand;
+        fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+        console.log("✅ Added 'test:e2e' script to package.json");
+    }
+    else {
+        console.log("ℹ️ 'test:e2e' script already exists in package.json. Skipping.");
+    }
+    // 2. Create playwright.config.ts
+    const configPath = path.join(process.cwd(), "playwright.config.ts");
+    if (!fs.existsSync(configPath)) {
+        const configContent = `import { defineConfig, devices } from "@playwright/test";
+
+/**
+ * Playwright configuration for Foundry VTT E2E testing.
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+  testDir: "./e2e",
+  timeout: 120000, // 2 minutes for slow Foundry boots
+  expect: {
+    timeout: 10000,
+  },
+  /* Run tests in files in parallel */
+  fullyParallel: true,
+  /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+  reporter: [["html", { open: "never" }]],
+  /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+  use: {
+    /* Base URL to use in actions like \`await page.goto('/')\`. */
+    baseURL: process.env.FOUNDRY_URL || "http://localhost:30000",
+
+    /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+    trace: "on-first-retry",
+  },
+
+  /* Configure projects for major browsers */
+  projects: [
+    {
+      name: "chromium",
+      use: {
+        ...devices["Desktop Chrome"],
+        viewport: { width: 1440, height: 900 },
+      },
+    },
+  ],
+});
+`;
+        fs.writeFileSync(configPath, configContent);
+        console.log("✅ Created playwright.config.ts");
+    }
+    else {
+        console.log("ℹ️ playwright.config.ts already exists. Skipping.");
+    }
+    // 3. Create e2e directory and a sample test
+    const e2eDir = path.join(process.cwd(), "e2e");
+    if (!fs.existsSync(e2eDir)) {
+        fs.mkdirSync(e2eDir);
+        console.log("✅ Created 'e2e' directory");
+    }
+    const sampleTestPath = path.join(e2eDir, "basic.spec.ts");
+    if (!fs.existsSync(sampleTestPath)) {
+        const sampleTestContent = `import { test, expect, useFoundry } from "@thefehr/foundry-playwright";
+
+/**
+ * This helper ensures that the Foundry VTT instance is fully set up
+ * with the desired world, system, and modules before any tests run.
+ */
+useFoundry(test, {
+  worldId: "test-world",
+  systemId: "dnd5e",
+  // moduleId: "my-module", // Uncomment and replace with your module ID
+});
+
+test("Foundry VTT is loaded and reachable", async ({ page }) => {
+  await page.goto("/");
+  
+  // Wait for the game to be ready (handled by foundrySetup, but good to check)
+  await expect(page).toHaveTitle(/Foundry VTT/);
+  
+  const gamePaused = await page.evaluate(() => game.paused);
+  console.log("Is the game paused?", gamePaused);
+});
+
+test("Can interact with Foundry State", async ({ foundry }) => {
+  // The 'foundry' fixture provides direct access to state manipulation
+  const actors = await foundry.state.getDocuments("Actor");
+  console.log(\`Found \${actors.length} actors in the world.\`);
+});
+`;
+        fs.writeFileSync(sampleTestPath, sampleTestContent);
+        console.log("✅ Created e2e/basic.spec.ts (sample test)");
+    }
+    else {
+        console.log("ℹ️ e2e/basic.spec.ts already exists. Skipping.");
+    }
+    // 4. Create .env.template
+    const envTemplatePath = path.join(process.cwd(), ".env.template");
+    if (!fs.existsSync(envTemplatePath)) {
+        const envContent = `FOUNDRY_ADMIN_KEY=password
+FOUNDRY_VERSION=13.351.0
+FOUNDRY_SYSTEM_ID=dnd5e
+`;
+        fs.writeFileSync(envTemplatePath, envContent);
+        console.log("✅ Created .env.template");
+    }
+    else {
+        console.log("ℹ️ .env.template already exists. Skipping.");
+    }
+    console.log("\n🎉 Setup complete! You can now run your tests with:");
+    console.log("   npm run test:e2e");
+}

package/dist/deprecations.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Scoped tracker for deprecation and warning messages.
+ * Allows adapters to register patterns that should be ignored or explicitly failed.
+ */
+export declare class DeprecationTracker {
+    private ignoredPatterns;
+    private failurePatterns;
+    /**
+     * Registers a pattern to be ignored.
+     */
+    registerIgnore(pattern: string | RegExp | (string | RegExp)[]): void;
+    /**
+     * Registers a pattern that should explicitly fail the test, even if it doesn't contain "deprecated".
+     */
+    registerFailure(pattern: string | RegExp | (string | RegExp)[]): void;
+    /**
+     * Checks if a warning message should be ignored.
+     */
+    shouldIgnore(text: string): boolean;
+    /**
+     * Checks if a warning message should cause a test failure.
+     */
+    shouldFail(text: string): boolean;
+}

package/dist/deprecations.js

@@ -0,0 +1,59 @@
+/**
+ * Scoped tracker for deprecation and warning messages.
+ * Allows adapters to register patterns that should be ignored or explicitly failed.
+ */
+export class DeprecationTracker {
+    ignoredPatterns = [
+        "namespaced under foundry", // V14 internal namespacing we handle
+    ];
+    failurePatterns = [];
+    /**
+     * Registers a pattern to be ignored.
+     */
+    registerIgnore(pattern) {
+        if (Array.isArray(pattern)) {
+            this.ignoredPatterns.push(...pattern);
+        }
+        else {
+            this.ignoredPatterns.push(pattern);
+        }
+    }
+    /**
+     * Registers a pattern that should explicitly fail the test, even if it doesn't contain "deprecated".
+     */
+    registerFailure(pattern) {
+        if (Array.isArray(pattern)) {
+            this.failurePatterns.push(...pattern);
+        }
+        else {
+            this.failurePatterns.push(pattern);
+        }
+    }
+    /**
+     * Checks if a warning message should be ignored.
+     */
+    shouldIgnore(text) {
+        const lowerText = text.toLowerCase();
+        return this.ignoredPatterns.some((p) => {
+            if (typeof p === "string")
+                return lowerText.includes(p.toLowerCase());
+            return p.test(text);
+        });
+    }
+    /**
+     * Checks if a warning message should cause a test failure.
+     */
+    shouldFail(text) {
+        const lowerText = text.toLowerCase();
+        // Default failure for deprecations
+        if (lowerText.includes("deprecated") || lowerText.includes("deprecation")) {
+            return true;
+        }
+        // Check custom failure patterns
+        return this.failurePatterns.some((p) => {
+            if (typeof p === "string")
+                return lowerText.includes(p.toLowerCase());
+            return p.test(text);
+        });
+    }
+}

package/dist/docker.d.ts

@@ -0,0 +1,37 @@
+export interface DockerOrchestratorConfig {
+    version: string;
+    port?: number;
+    adminKey?: string;
+    username?: string;
+    password?: string;
+    dataDir?: string;
+    cacheDir?: string;
+    containerName?: string;
+    envFile?: string;
+}
+/**
+ * Programmatic orchestrator for Foundry VTT Docker containers.
+ * Uses direct docker commands instead of docker-compose for better control and zero-config for users.
+ */
+export declare class DockerFoundryOrchestrator {
+    private config;
+    constructor(config: DockerOrchestratorConfig);
+    /**
+     * Starts the Foundry VTT container.
+     */
+    start(): Promise<string>;
+    /**
+     * Generates the docker run command.
+     * @internal
+     */
+    getRunCommand(envPath: string): string;
+    /**
+     * Stops and removes the container.
+     */
+    stopAndRemove(): void;
+    /**
+     * Copies a local path into the container.
+     */
+    copyToContainer(localPath: string, containerPath: string): void;
+    private waitForReady;
+}

package/dist/docker.js

@@ -0,0 +1,140 @@
+import { execSync } from "child_process";
+import path from "path";
+import fs from "fs";
+/**
+ * Programmatic orchestrator for Foundry VTT Docker containers.
+ * Uses direct docker commands instead of docker-compose for better control and zero-config for users.
+ */
+export class DockerFoundryOrchestrator {
+    config;
+    constructor(config) {
+        this.config = {
+            version: config.version,
+            port: config.port || 30000,
+            adminKey: config.adminKey || "password",
+            username: config.username || process.env.FOUNDRY_USERNAME || "",
+            password: config.password || process.env.FOUNDRY_PASSWORD || "",
+            dataDir: config.dataDir || path.join(process.cwd(), "foundry_data"),
+            cacheDir: config.cacheDir || path.join(process.cwd(), ".foundry_cache"),
+            containerName: config.containerName || `foundry-playwright-${config.version.replace(/\./g, "-")}`,
+            envFile: config.envFile || ".env",
+        };
+    }
+    /**
+     * Starts the Foundry VTT container.
+     */
+    async start() {
+        console.log(`[DockerOrchestrator] Starting Foundry VTT v${this.config.version}...`);
+        // 1. Verify environment file
+        const envPath = path.resolve(this.config.envFile);
+        if (!fs.existsSync(envPath)) {
+            throw new Error(`[DockerOrchestrator] Environment file not found at ${envPath}. A valid .env file is required to avoid leaking credentials in logs.`);
+        }
+        const envContent = fs.readFileSync(envPath, "utf8");
+        const requiredVars = ["FOUNDRY_USERNAME", "FOUNDRY_PASSWORD", "FOUNDRY_ADMIN_KEY"];
+        for (const v of requiredVars) {
+            const regex = new RegExp(`^[ \\t]*${v}=`, "m");
+            if (!regex.test(envContent)) {
+                throw new Error(`[DockerOrchestrator] Environment file at ${envPath} is missing required variable: ${v}`);
+            }
+        }
+        // 2. Ensure directories exist
+        if (!fs.existsSync(this.config.dataDir))
+            fs.mkdirSync(this.config.dataDir, { recursive: true });
+        if (!fs.existsSync(this.config.cacheDir))
+            fs.mkdirSync(this.config.cacheDir, { recursive: true });
+        // 3. Stop/Remove existing container if it exists
+        this.stopAndRemove();
+        // 4. Pull image if missing
+        const image = `ghcr.io/felddy/foundryvtt:${this.config.version}`;
+        const imageExists = execSync(`docker images -q ${image}`, { encoding: "utf8" }).trim() !== "";
+        if (!imageExists) {
+            console.log(`[DockerOrchestrator] Image ${image} not found locally. Pulling...`);
+            execSync(`docker pull ${image}`, { stdio: "inherit" });
+        }
+        else {
+            console.log(`[DockerOrchestrator] Image ${image} already exists locally.`);
+            // Optional: try to pull to update, but ignore failures
+            try {
+                console.log(`[DockerOrchestrator] Attempting to update image ${image}...`);
+                execSync(`docker pull ${image}`, { stdio: "ignore" });
+            }
+            catch {
+                console.warn(`[DockerOrchestrator] Failed to update image ${image}, using local version.`);
+            }
+        }
+        // 5. Run container
+        const dockerCmd = this.getRunCommand(envPath);
+        console.log(`[DockerOrchestrator] Executing: docker run -d --name ${this.config.containerName} ... (using --env-file for security)`);
+        execSync(dockerCmd, { stdio: "inherit" });
+        // 6. Wait for healthy
+        await this.waitForReady();
+        return `http://localhost:${this.config.port}`;
+    }
+    /**
+     * Generates the docker run command.
+     * @internal
+     */
+    getRunCommand(envPath) {
+        const image = `ghcr.io/felddy/foundryvtt:${this.config.version}`;
+        return [
+            "docker run -d",
+            `--name ${this.config.containerName}`,
+            "--restart always",
+            `-p ${this.config.port}:30000`,
+            `--env-file "${path.resolve(envPath)}"`,
+            `-v "${path.resolve(this.config.dataDir)}:/data"`,
+            `-v "${path.resolve(this.config.cacheDir)}:/data/container_cache"`,
+            image,
+        ].join(" ");
+    }
+    /**
+     * Stops and removes the container.
+     */
+    stopAndRemove() {
+        console.log(`[DockerOrchestrator] Cleaning up container ${this.config.containerName}...`);
+        try {
+            execSync(`docker stop ${this.config.containerName}`, { stdio: "ignore" });
+            execSync(`docker rm ${this.config.containerName}`, { stdio: "ignore" });
+        }
+        catch { }
+    }
+    /**
+     * Copies a local path into the container.
+     */
+    copyToContainer(localPath, containerPath) {
+        console.log(`[DockerOrchestrator] Copying ${localPath} to ${this.config.containerName}:${containerPath}`);
+        // Ensure destination directory exists via an ephemeral container or exec (if running)
+        execSync(`docker exec ${this.config.containerName} mkdir -p ${path.dirname(containerPath)}`, {
+            stdio: "inherit",
+        });
+        execSync(`docker cp ${localPath} ${this.config.containerName}:${containerPath}`, {
+            stdio: "inherit",
+        });
+        // Fix permissions
+        execSync(`docker exec ${this.config.containerName} chown -R 1000:1000 ${containerPath}`, {
+            stdio: "inherit",
+        });
+    }
+    async waitForReady() {
+        const url = `http://localhost:${this.config.port}`;
+        console.log(`[DockerOrchestrator] Waiting for Foundry to be ready at ${url}...`);
+        let ready = false;
+        const maxAttempts = 150;
+        for (let i = 0; i < maxAttempts; i++) {
+            try {
+                const response = await fetch(url);
+                if (response.ok) {
+                    ready = true;
+                    break;
+                }
+            }
+            catch { }
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+        if (!ready) {
+            throw new Error("Foundry VTT failed to start within the timeout period.");
+        }
+        console.log("[DockerOrchestrator] Foundry is ready!");
+    }
+}

package/dist/fixtures.d.ts

@@ -0,0 +1,29 @@
+import { FoundryState } from "./state.js";
+import { FoundryUI } from "./ui/index.js";
+import { FoundryCanvas } from "./canvas.js";
+import { DeprecationTracker } from "./deprecations.js";
+import { FoundryPage } from "./types/index.js";
+/**
+ * Extended Playwright test fixtures for Foundry VTT.
+ */
+export interface FoundryFixtures {
+    /** Helper for Foundry VTT utilities. */
+    foundry: {
+        /** Direct state manipulation. */
+        state: FoundryState;
+        /** UI interaction and selectors. */
+        ui: FoundryUI;
+        /** WebGL Canvas interaction. */
+        canvas: FoundryCanvas;
+    };
+    /** Tracker for deprecation warnings. */
+    deprecationTracker: DeprecationTracker;
+    /** The Playwright Page object. */
+    page: FoundryPage;
+}
+/**
+ * Extended Playwright test fixture that monitors the browser console for critical errors and warnings,
+ * and provides Foundry-specific utilities.
+ */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & FoundryFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect } from "@playwright/test";

package/dist/fixtures.js

@@ -0,0 +1,112 @@
+import { test as base } from "@playwright/test";
+import { FoundryState } from "./state.js";
+import { FoundryUI } from "./ui/index.js";
+import { FoundryCanvas } from "./canvas.js";
+import { disableTour } from "./helpers.js";
+import { DeprecationTracker } from "./deprecations.js";
+import { initAllSystems } from "./systems/index.js";
+/**
+ * Extended Playwright test fixture that monitors the browser console for critical errors and warnings,
+ * and provides Foundry-specific utilities.
+ */
+export const test = base.extend({
+    deprecationTracker: async (_, use) => {
+        await use(new DeprecationTracker());
+    },
+    foundry: async ({ page, deprecationTracker }, use) => {
+        const systemId = process.env.FOUNDRY_SYSTEM_ID || "dnd5e";
+        const uiAdapterId = process.env.FOUNDRY_UI_ADAPTER || "default";
+        await use({
+            state: new FoundryState(page, systemId, deprecationTracker),
+            ui: new FoundryUI(page, uiAdapterId),
+            canvas: new FoundryCanvas(page),
+        });
+    },
+    page: async ({ page, deprecationTracker }, use) => {
+        // 1. Initial page setup
+        await disableTour(page);
+        // Attach tracker to page for non-fixture access (e.g. in adapters)
+        const foundryPage = page;
+        foundryPage.deprecationTracker = deprecationTracker;
+        // Initialize all known systems to register their deprecation patterns
+        initAllSystems(foundryPage);
+        const deprecations = [];
+        page.on("console", (msg) => {
+            const text = msg.text();
+            const type = msg.type();
+            if (text.includes("hardware acceleration") ||
+                text.includes("Skipping game canvas") ||
+                text.includes("Buffered socket event") ||
+                text.includes("[vite]"))
+                return;
+            if (type === "error")
+                console.error(`Browser Error: ${text}`);
+            if (type === "warning") {
+                if (deprecationTracker.shouldIgnore(text))
+                    return;
+                console.warn(`Browser Warning: ${text}`);
+                if (deprecationTracker.shouldFail(text)) {
+                    deprecations.push(text);
+                    return;
+                }
+                if (text.includes("Cannot read properties of null") ||
+                    text.includes("Failed data migration")) {
+                    throw new Error(`Critical Warning: ${text}`);
+                }
+            }
+            if (type === "log")
+                console.log(`Browser Log: ${text}`);
+        });
+        // 2. Pre-Test Synchronization
+        const syncModule = async () => {
+            const url = page.url();
+            if (url.includes("/game") || url.includes("/players")) {
+                console.log("[fixture] Synchronizing with game state...");
+                await page
+                    .waitForFunction(() => window.FP_VERIFY !== undefined, { timeout: 30000 })
+                    .catch(() => null);
+                // Wait for constructor readiness on V14
+                const isV14 = await page.evaluate(() => window.foundry?.applications?.api?.ApplicationV2 !== undefined ||
+                    document.querySelector('script[src*="foundry.mjs"]') !== null);
+                if (isV14) {
+                    await page
+                        .waitForFunction(() => {
+                        return (window.FakeAppV2 !== undefined && window.FakeTour !== undefined);
+                    }, {}, { timeout: 15000 })
+                        .catch(() => null);
+                }
+            }
+        };
+        await syncModule();
+        try {
+            await use(foundryPage);
+            // Report deprecations at the end of a successful test run
+            if (deprecations.length > 0) {
+                const uniqueDeprecations = Array.from(new Set(deprecations));
+                throw new Error(`Deprecation Warnings detected during test:\n${uniqueDeprecations.join("\n")}`);
+            }
+        }
+        catch (error) {
+            const verifyData = await page
+                .evaluate(() => {
+                if (!window.FP_VERIFY)
+                    return null;
+                // Return a shallow copy of log keys to avoid massive serialization
+                const logs = window.FP_VERIFY.logs;
+                const summary = {};
+                for (let key in logs) {
+                    summary[key] = logs[key].length + " entries";
+                }
+                return {
+                    summary,
+                    lastLogs: Object.fromEntries(Object.entries(logs).map(([k, v]) => [k, v.slice(-1)])),
+                };
+            })
+                .catch(() => null);
+            if (verifyData)
+                console.error(`[FP_VERIFY DUMP on Failure]:\n${JSON.stringify(verifyData, null, 2)}`);
+            throw error;
+        }
+    },
+});
+export { expect } from "@playwright/test";

package/dist/helpers.d.ts

@@ -0,0 +1,100 @@
+import { Page, Locator } from "@playwright/test";
+/**
+ * Loads the verification registry from verified-versions.json.
+ */
+export declare function getVerificationRegistry(): any[];
+/**
+ * Helper to automatically set up a Foundry VTT instance before all tests in a file.
+ * Reduces boilerplate in spec files.
+ * @param test The Playwright test object.
+ * @param config Foundry setup configuration.
+ */
+export declare function useFoundry(test: any, config?: any): void;
+/**
+ * Validates the current Foundry/System/Module stack against the registry.
+ */
+export declare function validateStack(page: Page, targetVersion?: string | number): Promise<"untested" | "incompatible" | "stable" | undefined>;
+/**
+ * Aggressively removes Foundry VTT tours and overlays from the DOM and localStorage.
+ * @param page The Playwright Page object.
+ */
+export declare function disableTour(page: Page): Promise<void>;
+/**
+ * Navigates to a specific tab by name or ID.
+ * @param page The Playwright Page object.
+ * @param tabName The logical name or data-tab value of the tab.
+ */
+export declare function switchTab(page: Page, tabName: string): Promise<void>;
+/**
+ * Navigates to the Systems tab and opens the installation dialog.
+ * @param page The Playwright Page object.
+ */
+export declare function openSystemInstallDialog(page: Page): Promise<Locator>;
+/**
+ * Navigates to the Modules tab and opens the installation dialog.
+ * @param page The Playwright Page object.
+ */
+export declare function openModuleInstallDialog(page: Page): Promise<Locator>;
+/**
+ * Installs a system from a manifest URL.
+ * @param page The Playwright Page object.
+ * @param manifestUrl The URL to the system.json manifest.
+ */
+export declare function installSystemFromManifest(page: Page, manifestUrl: string): Promise<void>;
+/**
+ * Installs a module from a manifest URL.
+ * @param page The Playwright Page object.
+ * @param manifestUrl The URL to the module.json manifest.
+ */
+export declare function installModuleFromManifest(page: Page, manifestUrl: string): Promise<void>;
+/**
+ * Waits for the Foundry VTT game object to be fully initialized and ready.
+ * @param page The Playwright Page object.
+ */
+export declare function waitForReady(page: Page): Promise<void>;
+/**
+ * Executes a function after ensuring a log has been emitted via FP_VERIFY.
+ * @param page The Playwright Page object.
+ * @param key The log key to wait for.
+ * @param predicate A function to test the log data.
+ * @param extraData Optional extra data to pass to the predicate.
+ */
+export declare function verifyResult(page: Page, key: string, predicate: (data: any, extra?: any) => boolean, extraData?: any, options?: {
+    timeout?: number;
+}): Promise<void>;
+/**
+ * Waits for a specific actor flag to be set to a value.
+ */
+export declare function waitForActorFlag(page: Page, actorName: string, flag: string, value: any): Promise<void>;
+/**
+ * Waits for specific actor data to be updated.
+ */
+export declare function waitForActorData(page: Page, actorName: string, path: string, value: any): Promise<void>;
+/**
+ * Waits for a game setting to be set.
+ */
+export declare function waitForSetting(page: Page, module: string, key: string, value: any): Promise<void>;
+/**
+ * Clears the FP_VERIFY log registry.
+ */
+export declare function clearFPVerify(page: Page): Promise<void>;
+/**
+ * Handles the Foundry VTT reload dialog.
+ */
+export declare function handleReload(page: Page): Promise<void>;
+/**
+ * Fills a field in a visible dialog.
+ */
+export declare function fillDialogField(page: Page, label: string, value: string): Promise<void>;
+/**
+ * Performs the full module activation flow for a list of modules.
+ */
+export declare function handleModuleActivationFlow(page: Page, moduleIds: string[]): Promise<void>;
+/**
+ * Simulates a drop from a compendium onto a target.
+ */
+export declare function dropCompendiumItem(page: Page, targetSelector: string, pack: string, itemId: string): Promise<void>;
+/**
+ * Simulates a Foundry VTT drag-and-drop event.
+ */
+export declare function simulateFoundryDrop(page: Page, targetSelector: string, data: any): Promise<void>;