@thefehr/foundry-playwright 0.2.1

package/dist/state.js

@@ -0,0 +1,321 @@
+import { UserRole } from "./types/index.js";
+import { getSystemStateAdapter } from "./systems/index.js";
+/**
+ * Provides methods for direct manipulation of the Foundry VTT state.
+ */
+export class FoundryState {
+    page;
+    systemId;
+    deprecationTracker;
+    adapter;
+    constructor(page, systemId = "dnd5e", deprecationTracker) {
+        this.page = page;
+        this.systemId = systemId;
+        this.deprecationTracker = deprecationTracker;
+        this.adapter = getSystemStateAdapter(systemId, page);
+    }
+    /**
+     * Sets the system adapter to use.
+     */
+    setSystem(systemId) {
+        this.systemId = systemId;
+        this.adapter = getSystemStateAdapter(systemId, this.page);
+    }
+    /**
+     * Aggressively removes properties known to trigger deprecation warnings on access.
+     * This is used before returning data from page.evaluate.
+     */
+    static get SanitizerScript() {
+        return `(obj) => {
+        if (!obj || typeof obj !== 'object') return obj;
+        const deprecatedDnD5e = ['darkvision', 'blindsight', 'tremorsense', 'truesight', 'special'];
+        const cleanSenses = (o) => {
+            if (!o || typeof o !== 'object') return o;
+            const result = Array.isArray(o) ? [] : {};
+            for (let key in o) {
+                if (key === 'senses') {
+                    const senses = o[key];
+                    const cleanS = Array.isArray(senses) ? [] : {};
+                    for (let skey in senses) {
+                        if (deprecatedDnD5e.includes(skey)) continue;
+                        cleanS[skey] = senses[skey];
+                    }
+                    result[key] = cleanS;
+                } else {
+                    result[key] = cleanSenses(o[key]);
+                }
+            }
+            return result;
+        };
+        return cleanSenses(obj);
+    }`;
+    }
+    /**
+     * Creates a new Foundry VTT document.
+     * @param documentName The type of document (e.g., "Actor", "Item").
+     * @param data The document data.
+     */
+    async createDocument(documentName, data) {
+        return this.page.evaluate(async ({ documentName, data, sanitizer }) => {
+            // @ts-ignore
+            const cls = CONFIG[documentName].documentClass;
+            const doc = await cls.create(data);
+            if (!doc)
+                return null;
+            // Use raw _source to avoid getters/deprecations
+            const obj = doc._source ? JSON.parse(JSON.stringify(doc._source)) : doc.toObject();
+            const sanitize = new Function(`return ${sanitizer}`)();
+            return sanitize(obj);
+        }, { documentName, data, sanitizer: FoundryState.SanitizerScript });
+    }
+    /**
+     * Updates an existing document in Foundry VTT.
+     * @param documentName The name of the document type.
+     * @param id The ID of the document to update.
+     * @param delta The data to update.
+     */
+    async updateDocument(documentName, id, delta) {
+        return this.page.evaluate(({ documentName, id, delta }) => {
+            // @ts-ignore
+            const doc = game.collections.get(documentName).get(id);
+            return doc.update(delta);
+        }, { documentName, id, delta });
+    }
+    /**
+     * Deletes a document in Foundry VTT.
+     * @param documentName The name of the document type.
+     * @param id The ID of the document to delete.
+     */
+    async deleteDocument(documentName, id) {
+        return this.page.evaluate(({ documentName, id }) => {
+            // @ts-ignore
+            const doc = game.collections.get(documentName).get(id);
+            return doc.delete();
+        }, { documentName, id });
+    }
+    /**
+     * Gets a document by its ID.
+     * @param documentName The name of the document type.
+     * @param id The ID of the document.
+     */
+    async getDocument(documentName, id) {
+        return this.page.evaluate(({ documentName, id, sanitizer }) => {
+            // @ts-ignore
+            const doc = game.collections.get(documentName).get(id);
+            if (!doc)
+                return null;
+            // Use raw _source to avoid getters/deprecations
+            const obj = doc._source ? JSON.parse(JSON.stringify(doc._source)) : doc.toObject();
+            const sanitize = new Function(`return ${sanitizer}`)();
+            return sanitize(obj);
+        }, { documentName, id, sanitizer: FoundryState.SanitizerScript });
+    }
+    /**
+     * Gets a document by its name.
+     * @param documentName The name of the document type.
+     * @param name The name of the document.
+     */
+    async getDocumentByName(documentName, name) {
+        return this.page.evaluate(({ documentName, name, sanitizer }) => {
+            const g = window.game;
+            const collection = g.collections.get(documentName) || g[documentName.toLowerCase() + "s"];
+            const doc = collection.getName(name);
+            if (!doc)
+                return null;
+            // Use raw _source to avoid getters/deprecations
+            const obj = doc._source ? JSON.parse(JSON.stringify(doc._source)) : doc.toObject();
+            const sanitize = new Function(`return ${sanitizer}`)();
+            return sanitize(obj);
+        }, { documentName, name, sanitizer: FoundryState.SanitizerScript });
+    }
+    /**
+     * Creates a new User.
+     */
+    async createUser(name, role = UserRole.PLAYER, password) {
+        return this.page.evaluate(({ name, role, password }) => {
+            // @ts-ignore
+            return User.create({ name, role, password });
+        }, { name, role, password });
+    }
+    /**
+     * Sets a user's role.
+     */
+    async setUserRole(userId, role) {
+        return this.page.evaluate(({ userId, role }) => {
+            // @ts-ignore
+            const user = game.users.get(userId);
+            if (!user)
+                throw new Error(`User not found: ${userId}`);
+            return user.update({ role });
+        }, { userId, role });
+    }
+    /**
+     * Configures a specific permission for a user role.
+     */
+    async setRolePermission(permission, role, allowed) {
+        return this.page.evaluate(({ permission, role, allowed }) => {
+            // @ts-ignore
+            const current = game.settings.get("core", "permissions") || {};
+            const update = { ...current, [permission]: { ...current[permission], [role]: allowed } };
+            // @ts-ignore
+            return game.settings.set("core", "permissions", update);
+        }, { permission, role, allowed });
+    }
+    /**
+     * Grants currency to an actor.
+     * @param actorName The name of the actor.
+     * @param amount The amount of currency to grant.
+     * @param currency The type of currency (e.g., "gp", "sp").
+     */
+    async grantCurrency(actorName, amount, currency = "gp") {
+        return this.adapter.grantCurrency(this.page, actorName, amount, currency);
+    }
+    /**
+     * Gets the verification parameters for a currency update.
+     */
+    getCurrencyVerifyParams(actorName, amount, currency = "gp") {
+        return this.adapter.getCurrencyVerifyParams(actorName, amount, currency);
+    }
+    /**
+     * Sets an actor's HP.
+     * @param actorName The name of the actor.
+     * @param value The new HP value.
+     * @param max The new max HP value (optional).
+     */
+    async setActorHP(actorName, value, max) {
+        return this.adapter.setActorHP(this.page, actorName, value, max);
+    }
+    /**
+     * Rolls a specific roll for an actor.
+     * @param actorName The name of the actor.
+     * @param formula The roll formula (e.g., "1d20 + 5").
+     * @param label A label for the roll.
+     */
+    async roll(actorName, formula, label = "Test Roll") {
+        return this.page.evaluate(({ actorName, formula, label }) => {
+            // @ts-ignore
+            const actor = game.actors.getName(actorName);
+            if (!actor)
+                throw new Error(`Actor not found: ${actorName}`);
+            // @ts-ignore
+            const roll = new Roll(formula, actor.getRollData());
+            return roll.toMessage({ flavor: label });
+        }, { actorName, formula, label });
+    }
+    /**
+     * Executes a macro by name.
+     * @param name The name of the macro.
+     * @param args Arguments to pass to the macro.
+     */
+    async executeMacro(name, ...args) {
+        return this.page.evaluate(({ name, args }) => {
+            // @ts-ignore
+            const macro = game.macros.getName(name);
+            return macro.execute(...args);
+        }, { name, args });
+    }
+    /**
+     * Manually triggers a Foundry VTT hook.
+     * @param hookName The name of the hook (e.g., "renderActorSheet").
+     * @param args Arguments to pass to the hook.
+     */
+    async triggerHook(hookName, ...args) {
+        return this.page.evaluate(({ hookName, args }) => {
+            return window.Hooks.call(hookName, ...args);
+        }, { hookName, args });
+    }
+    /**
+     * Emits a socket event via the Foundry VTT socket.
+     * @param eventName The name of the event.
+     * @param data The data to emit.
+     */
+    async emitSocket(eventName, data) {
+        return this.page.evaluate(({ eventName, data }) => {
+            return window.game.socket.emit(eventName, data);
+        }, { eventName, data });
+    }
+    /**
+     * Waits for a specific Foundry VTT hook to be called.
+     * @param hookName The name of the hook.
+     * @param timeout The timeout in milliseconds.
+     * @returns The first argument passed to the hook.
+     */
+    async waitForHook(hookName, timeout = 10000) {
+        await this.page.evaluate((hookName) => {
+            window._hookLogs = window._hookLogs || {};
+            window._hookLogs[hookName] = window._hookLogs[hookName] || [];
+            window.Hooks.on(hookName, (...args) => {
+                window._hookLogs[hookName].push(args);
+            });
+        }, hookName);
+        await this.page.waitForFunction((name) => {
+            return window._hookLogs?.[name]?.length > 0;
+        }, hookName, { timeout });
+        return this.page.evaluate((name) => {
+            const logs = window._hookLogs[name];
+            window._hookLogs[name] = [];
+            return logs[0]?.[0]; // Return the first argument of the first call
+        }, hookName);
+    }
+    /**
+     * Waits for a specific socket event to be received.
+     * @param eventName The name of the event.
+     * @param timeout The timeout in milliseconds.
+     */
+    async waitForSocket(eventName, timeout = 10000) {
+        await this.page.evaluate((eventName) => {
+            window._socketLogs = window._socketLogs || {};
+            window._socketLogs[eventName] = window._socketLogs[eventName] || 0;
+            window.game.socket.on(eventName, () => {
+                window._socketLogs[eventName]++;
+            });
+        }, eventName);
+        await this.page.waitForFunction((name) => {
+            return window._socketLogs?.[name] > 0;
+        }, eventName, { timeout });
+        return this.page.evaluate((name) => {
+            const count = window._socketLogs[name];
+            window._socketLogs[name] = 0;
+            return count;
+        }, eventName);
+    }
+    /**
+     * Assigns an actor to a user.
+     */
+    async assignActorToUser(userId, actorId) {
+        return this.page.evaluate(({ userId, actorId }) => {
+            // @ts-ignore
+            const user = game.users.get(userId);
+            if (!user)
+                throw new Error(`User not found: ${userId}`);
+            return user.update({ character: actorId });
+        }, { userId, actorId });
+    }
+    /**
+     * Updates an existing user.
+     */
+    async updateUser(userId, delta) {
+        return this.page.evaluate(({ userId, delta }) => {
+            // @ts-ignore
+            const user = game.users.get(userId);
+            if (!user)
+                throw new Error(`User not found: ${userId}`);
+            return user.update(delta);
+        }, { userId, delta });
+    }
+    /**
+     * Creates a test actor.
+     */
+    async createTestActor(name = "Test Actor") {
+        const { type, system } = this.adapter.getTestActorData(name);
+        return this.createDocument("Actor", { name, type, system });
+    }
+    /**
+     * Sets or updates a Foundry VTT setting.
+     */
+    async setSetting(module, key, value) {
+        return this.page.evaluate(({ module, key, value }) => {
+            return window.game.settings.set(module, key, value);
+        }, { module, key, value });
+    }
+}

package/dist/systems/base.d.ts

@@ -0,0 +1,48 @@
+import { FoundryPage } from "../types/index.js";
+/**
+ * Interface for system-specific state manipulation logic.
+ */
+export interface SystemStateAdapter {
+    /** The system ID this adapter handles. */
+    readonly id: string;
+    /**
+     * Grants currency to an actor.
+     */
+    grantCurrency(page: FoundryPage, actorName: string, amount: number, currency: string): Promise<any>;
+    /**
+     * Provides the system-specific data structure for a test actor.
+     */
+    getTestActorData(name: string): {
+        type: string;
+        system: any;
+    };
+    /**
+     * Sets an actor's HP.
+     */
+    setActorHP(page: FoundryPage, actorName: string, value: number, max?: number): Promise<any>;
+    /**
+     * Returns the log key and a predicate to verify a currency update in verifyResult.
+     */
+    getCurrencyVerifyParams(actorName: string, amount: number, currency: string): {
+        key: string;
+        predicate: (data: any, extra?: any) => boolean;
+    };
+}
+/**
+ * Base implementation of SystemStateAdapter with default (often DnD5e-like) logic.
+ */
+export declare abstract class BaseSystemStateAdapter implements SystemStateAdapter {
+    protected page?: FoundryPage | undefined;
+    abstract id: string;
+    constructor(page?: FoundryPage | undefined);
+    grantCurrency(page: FoundryPage, actorName: string, amount: number, currency: string): Promise<any>;
+    getTestActorData(_name: string): {
+        type: string;
+        system: any;
+    };
+    setActorHP(page: FoundryPage, actorName: string, value: number, max?: number): Promise<any>;
+    getCurrencyVerifyParams(_actorName: string, _amount: number, _currency: string): {
+        key: string;
+        predicate: (data: any, extra?: any) => boolean;
+    };
+}

package/dist/systems/base.js

@@ -0,0 +1,57 @@
+/**
+ * Base implementation of SystemStateAdapter with default (often DnD5e-like) logic.
+ */
+export class BaseSystemStateAdapter {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    async grantCurrency(page, actorName, amount, currency) {
+        return page.evaluate(({ actorName, amount, currency }) => {
+            const actor = window.game.actors.getName(actorName);
+            if (!actor)
+                throw new Error(`Actor not found: ${actorName}`);
+            const current = (actor.system.currency?.[currency] || 0) + amount;
+            return actor.update({ [`system.currency.${currency}`]: current });
+        }, { actorName, amount, currency });
+    }
+    getTestActorData(_name) {
+        return {
+            type: "character",
+            system: {
+                attributes: { hp: { value: 10, max: 10 } },
+            },
+        };
+    }
+    async setActorHP(page, actorName, value, max) {
+        return page.evaluate(({ actorName, value, max }) => {
+            const actor = window.game.actors.getName(actorName);
+            if (!actor)
+                throw new Error(`Actor not found: ${actorName}`);
+            const update = { "system.attributes.hp.value": value };
+            if (max !== undefined)
+                update["system.attributes.hp.max"] = max;
+            return actor.update(update);
+        }, { actorName, value, max });
+    }
+    getCurrencyVerifyParams(_actorName, _amount, _currency) {
+        return {
+            key: "actor-update",
+            predicate: (data, extra) => {
+                // Broadly match any update that touches currency for the target actor
+                if (data.name !== extra.actorName)
+                    return false;
+                // Deep check for the expected currency value in the delta
+                const delta = data.delta || {};
+                // Check for direct property update: "system.currency.gp": 100
+                if (delta[`system.currency.${extra.currency}`] === extra.amount)
+                    return true;
+                // Check for nested update: { system: { currency: { gp: 100 } } }
+                const nestedVal = delta.system?.currency?.[extra.currency];
+                if (nestedVal === extra.amount)
+                    return true;
+                return false;
+            },
+        };
+    }
+}

package/dist/systems/dnd5e.d.ts

@@ -0,0 +1,27 @@
+import { FoundryPage } from "../types/index.js";
+import { BaseSystemStateAdapter } from "./base.js";
+/**
+ * State adapter for the D&D 5th Edition system.
+ */
+export declare class DnD5eStateAdapter extends BaseSystemStateAdapter {
+    readonly id = "dnd5e";
+    constructor(page?: FoundryPage);
+    getTestActorData(_name: string): {
+        type: string;
+        system: {
+            details: {
+                senses: {
+                    ranges: {
+                        darkvision: number;
+                    };
+                };
+            };
+            attributes: {
+                hp: {
+                    value: number;
+                    max: number;
+                };
+            };
+        };
+    };
+}

package/dist/systems/dnd5e.js

@@ -0,0 +1,30 @@
+import { BaseSystemStateAdapter } from "./base.js";
+/**
+ * State adapter for the D&D 5th Edition system.
+ */
+export class DnD5eStateAdapter extends BaseSystemStateAdapter {
+    id = "dnd5e";
+    constructor(page) {
+        super(page);
+        if (page?.deprecationTracker) {
+            page.deprecationTracker.registerFailure(["has moved to", "senses", "dnd5e"]);
+        }
+    }
+    getTestActorData(_name) {
+        return {
+            type: "character",
+            system: {
+                details: {
+                    senses: {
+                        ranges: {
+                            darkvision: 60,
+                        },
+                    },
+                },
+                attributes: {
+                    hp: { value: 10, max: 10 },
+                },
+            },
+        };
+    }
+}

package/dist/systems/index.d.ts

@@ -0,0 +1,13 @@
+import { FoundryPage } from "../types/index.js";
+import { SystemStateAdapter } from "./base.js";
+/**
+ * Gets a system state adapter by its ID.
+ */
+export declare function getSystemStateAdapter(id: string, page?: FoundryPage): SystemStateAdapter;
+/**
+ * Initializes all known system adapters to register their deprecation patterns.
+ */
+export declare function initAllSystems(page: FoundryPage): void;
+export * from "./base.js";
+export * from "./dnd5e.js";
+export * from "./pf2e.js";

package/dist/systems/index.js

@@ -0,0 +1,20 @@
+import { DnD5eStateAdapter } from "./dnd5e.js";
+import { PF2eStateAdapter } from "./pf2e.js";
+/**
+ * Gets a system state adapter by its ID.
+ */
+export function getSystemStateAdapter(id, page) {
+    if (id === "pf2e")
+        return new PF2eStateAdapter(page);
+    return new DnD5eStateAdapter(page);
+}
+/**
+ * Initializes all known system adapters to register their deprecation patterns.
+ */
+export function initAllSystems(page) {
+    new DnD5eStateAdapter(page);
+    new PF2eStateAdapter(page);
+}
+export * from "./base.js";
+export * from "./dnd5e.js";
+export * from "./pf2e.js";

package/dist/systems/pf2e.d.ts

@@ -0,0 +1,25 @@
+import { FoundryPage } from "../types/index.js";
+import { BaseSystemStateAdapter } from "./base.js";
+/**
+ * State adapter for the Pathfinder 2nd Edition system.
+ */
+export declare class PF2eStateAdapter extends BaseSystemStateAdapter {
+    readonly id = "pf2e";
+    constructor(page?: FoundryPage);
+    grantCurrency(page: FoundryPage, actorName: string, amount: number, currency: string): Promise<any>;
+    getTestActorData(_name: string): {
+        type: string;
+        system: {
+            attributes: {
+                hp: {
+                    value: number;
+                    max: number;
+                };
+            };
+        };
+    };
+    getCurrencyVerifyParams(actorName: string, amount: number, currency: string): {
+        key: string;
+        predicate: (data: any, extra?: any) => boolean;
+    };
+}

package/dist/systems/pf2e.js

@@ -0,0 +1,62 @@
+import { BaseSystemStateAdapter } from "./base.js";
+/**
+ * State adapter for the Pathfinder 2nd Edition system.
+ */
+export class PF2eStateAdapter extends BaseSystemStateAdapter {
+    id = "pf2e";
+    constructor(page) {
+        super(page);
+        if (page?.deprecationTracker) {
+            page.deprecationTracker.registerIgnore(["template.json is deprecated"]);
+        }
+    }
+    async grantCurrency(page, actorName, amount, currency) {
+        return page.evaluate(async ({ actorName, amount, currency }) => {
+            const actor = window.game.actors.getName(actorName);
+            if (!actor)
+                throw new Error(`Actor not found: ${actorName}`);
+            // Create the treasure item
+            const [newItem] = await actor.createEmbeddedDocuments("Item", [
+                {
+                    name: `${currency.toUpperCase()} Coins`,
+                    type: "treasure",
+                    system: {
+                        denomination: currency,
+                        quantity: amount,
+                    },
+                },
+            ]);
+            // Definitively log to the verification registry
+            // @ts-ignore
+            if (window.FP_VERIFY) {
+                window.FP_VERIFY.log("pf2e-currency-added", {
+                    actorName,
+                    amount,
+                    currency,
+                    itemId: newItem.id,
+                });
+            }
+            return newItem;
+        }, { actorName, amount, currency });
+    }
+    getTestActorData(_name) {
+        return {
+            type: "character",
+            system: {
+                attributes: {
+                    hp: { value: 10, max: 10 },
+                },
+            },
+        };
+    }
+    getCurrencyVerifyParams(actorName, amount, currency) {
+        return {
+            key: "pf2e-currency-added",
+            predicate: (data, extra) => {
+                return (data.actorName === extra.actorName &&
+                    data.currency === extra.currency &&
+                    data.amount === extra.amount);
+            },
+        };
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,18 @@
+import { Page } from "@playwright/test";
+import { DeprecationTracker } from "../deprecations.js";
+/**
+ * Extended Playwright Page with Foundry-specific properties.
+ */
+export interface FoundryPage extends Page {
+    deprecationTracker?: DeprecationTracker;
+}
+/**
+ * Foundry VTT User Roles as defined in CONST.USER_ROLES
+ */
+export declare enum UserRole {
+    NONE = 0,
+    PLAYER = 1,
+    TRUSTED = 2,
+    ASSISTANT = 3,
+    GAMEMASTER = 4
+}

package/dist/types/index.js

@@ -0,0 +1,11 @@
+/**
+ * Foundry VTT User Roles as defined in CONST.USER_ROLES
+ */
+export var UserRole;
+(function (UserRole) {
+    UserRole[UserRole["NONE"] = 0] = "NONE";
+    UserRole[UserRole["PLAYER"] = 1] = "PLAYER";
+    UserRole[UserRole["TRUSTED"] = 2] = "TRUSTED";
+    UserRole[UserRole["ASSISTANT"] = 3] = "ASSISTANT";
+    UserRole[UserRole["GAMEMASTER"] = 4] = "GAMEMASTER";
+})(UserRole || (UserRole = {}));

package/dist/ui/base.d.ts

@@ -0,0 +1,35 @@
+import { Page } from "@playwright/test";
+/**
+ * Interface for UI-specific logic and selectors in Foundry VTT.
+ */
+export interface UIAdapter {
+    /** The unique ID of the module or system this adapter is for. */
+    id: string;
+    /**
+     * Returns a selector for an actor sheet.
+     */
+    getActorSheetSelector(): string;
+    /**
+     * Switches to a specific tab on an application (e.g., Actor sheet).
+     * @param page The Playwright Page object.
+     * @param appSelector The selector for the application window.
+     * @param tabName The name of the tab to switch to.
+     */
+    switchAppTab(page: Page, appSelector: string, tabName: string): Promise<void>;
+    /**
+     * Expands a collapsible section if it is currently collapsed.
+     * @param page The Playwright Page object.
+     * @param appSelector The selector for the application window.
+     * @param sectionName The name/label of the section.
+     */
+    handleCollapsibleSection(page: Page, appSelector: string, sectionName: string): Promise<void>;
+}
+/**
+ * Default UI adapter for standard Foundry VTT interface.
+ */
+export declare class DefaultUIAdapter implements UIAdapter {
+    id: string;
+    getActorSheetSelector(): string;
+    switchAppTab(page: Page, appSelector: string, tabName: string): Promise<void>;
+    handleCollapsibleSection(page: Page, appSelector: string, sectionName: string): Promise<void>;
+}