@microsoft/fast-test-harness 0.1.0

package/dist/esm/build/generate-webui-templates.test.js

@@ -0,0 +1,179 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { generateWebuiTemplates } from "@microsoft/fast-test-harness/build/generate-webui-templates.js";
+test.describe("generateWebuiTemplates", () => {
+    let tempDir;
+    test.beforeEach(async () => {
+        tempDir = await mkdtemp(join(tmpdir(), "fast-webui-templ-"));
+    });
+    test.afterEach(async () => {
+        await rm(tempDir, { recursive: true, force: true });
+    });
+    test("should generate a webui template without f-template wrapper", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "badge.template.js"), `export const template = {
+                html: "<template><slot></slot></template>",
+                factories: {}
+            };`);
+        await generateWebuiTemplates({ cwd: tempDir, tagPrefix: "mai" });
+        const html = await readFile(join(distDir, "badge.template-webui.html"), "utf8");
+        assert.ok(html.includes('<template shadowrootmode="open">'));
+        assert.ok(html.includes("<slot></slot>"));
+        assert.ok(!html.includes("<f-template"), "should not have f-template wrapper");
+        assert.ok(!html.includes("{{styles}}"), "should not have styles marker");
+    });
+    test("should write to outDir when specified", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "card.template.js"), `export const template = {
+                html: "<template><div>card</div></template>",
+                factories: {}
+            };`);
+        await generateWebuiTemplates({
+            cwd: tempDir,
+            outDir: "out",
+            tagPrefix: "fast",
+        });
+        const html = await readFile(join(tempDir, "out", "card.template-webui.html"), "utf8");
+        assert.ok(html.includes('<template shadowrootmode="open">'));
+    });
+    test("should skip modules without a template export", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "empty.template.js"), `export const styles = ":host {}";`);
+        await generateWebuiTemplates({ cwd: tempDir, tagPrefix: "fast" });
+        try {
+            await readFile(join(distDir, "empty.template-webui.html"), "utf8");
+            assert.fail("Should not have created an HTML file");
+        }
+        catch (err) {
+            assert.strictEqual(err.code, "ENOENT");
+        }
+    });
+    test("should apply a format function", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "text.template.js"), `export const template = {
+                html: "<template><span>text</span></template>",
+                factories: {}
+            };`);
+        await generateWebuiTemplates({
+            cwd: tempDir,
+            tagPrefix: "fast",
+            format: html => `<!-- webui-formatted -->\n${html}`,
+        });
+        const html = await readFile(join(distDir, "text.template-webui.html"), "utf8");
+        assert.ok(html.startsWith("<!-- webui-formatted -->"));
+    });
+    test("should add shadowrootdelegatesfocus from definition-async", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "input.template.js"), `export const template = {
+                html: "<template><input /></template>",
+                factories: {}
+            };`);
+        await writeFile(join(distDir, "input.definition-async.js"), `export const definition = {
+                name: "fast-input",
+                shadowOptions: { delegatesFocus: true },
+            };`);
+        await generateWebuiTemplates({ cwd: tempDir, tagPrefix: "fast" });
+        const html = await readFile(join(distDir, "input.template-webui.html"), "utf8");
+        assert.ok(html.includes("shadowrootdelegatesfocus"), `should include delegatesFocus, got: ${html}`);
+    });
+    test("should not add shadowrootdelegatesfocus when absent", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "div.template.js"), `export const template = {
+                html: "<template><div>hello</div></template>",
+                factories: {}
+            };`);
+        await generateWebuiTemplates({ cwd: tempDir, tagPrefix: "fast" });
+        const html = await readFile(join(distDir, "div.template-webui.html"), "utf8");
+        assert.ok(!html.includes("shadowrootdelegatesfocus"));
+    });
+    test("should strip the {{styles}} marker from output", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        // The template contains nested content that would produce a styles marker
+        // during f-template generation (convertTemplate injects it).
+        await writeFile(join(distDir, "label.template.js"), `export const template = {
+                html: "<template><label>Name</label></template>",
+                factories: {}
+            };`);
+        await generateWebuiTemplates({ cwd: tempDir, tagPrefix: "mai" });
+        const html = await readFile(join(distDir, "label.template-webui.html"), "utf8");
+        assert.ok(!html.includes("{{styles}}"), `should not contain styles marker: ${html}`);
+        assert.ok(!html.includes("{%styles%}"), `should not contain alt styles marker: ${html}`);
+    });
+    test("should handle modules with a default export", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "icon.template.js"), `const template = {
+                html: "<template><svg></svg></template>",
+                factories: {}
+            };
+            export default template;`);
+        await generateWebuiTemplates({ cwd: tempDir, tagPrefix: "fast" });
+        const html = await readFile(join(distDir, "icon.template-webui.html"), "utf8");
+        assert.ok(html.includes('<template shadowrootmode="open">'));
+        assert.ok(html.includes("<svg></svg>"));
+    });
+    test("should handle multiple template modules in one pass", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "button.template.js"), `export const template = {
+                html: "<template><button><slot></slot></button></template>",
+                factories: {}
+            };`);
+        await writeFile(join(distDir, "badge.template.js"), `export const template = {
+                html: "<template><span><slot></slot></span></template>",
+                factories: {}
+            };`);
+        await generateWebuiTemplates({ cwd: tempDir, tagPrefix: "mai" });
+        const buttonHtml = await readFile(join(distDir, "button.template-webui.html"), "utf8");
+        const badgeHtml = await readFile(join(distDir, "badge.template-webui.html"), "utf8");
+        assert.ok(buttonHtml.includes("<button>"));
+        assert.ok(badgeHtml.includes("<span>"));
+    });
+    test("should gracefully handle a format function that throws", async () => {
+        const distDir = join(tempDir, "dist");
+        await mkdir(distDir, { recursive: true });
+        await writeFile(join(distDir, "broken.template.js"), `export const template = {
+                html: "<template><div>ok</div></template>",
+                factories: {}
+            };`);
+        // Should not throw — just warn and skip formatting.
+        await generateWebuiTemplates({
+            cwd: tempDir,
+            tagPrefix: "fast",
+            format: () => {
+                throw new Error("format boom");
+            },
+        });
+        const html = await readFile(join(distDir, "broken.template-webui.html"), "utf8");
+        // The file should still be written (unformatted).
+        assert.ok(html.includes("<div>ok</div>"));
+    });
+    test("should use a custom glob pattern", async () => {
+        const distDir = join(tempDir, "dist");
+        const sub = join(distDir, "components");
+        await mkdir(sub, { recursive: true });
+        // Use the standard .template.js suffix so basename extraction works
+        await writeFile(join(sub, "alert.template.js"), `export const template = {
+                html: "<template><div role='alert'></div></template>",
+                factories: {}
+            };`);
+        await generateWebuiTemplates({
+            cwd: tempDir,
+            tagPrefix: "fast",
+            pattern: "components/*.template.js",
+        });
+        const html = await readFile(join(sub, "alert.template-webui.html"), "utf8");
+        assert.ok(html.includes("role="), `got: ${html}`);
+        assert.ok(html.includes("alert"), `got: ${html}`);
+    });
+});

package/dist/esm/fixtures/assertions.js

@@ -0,0 +1,49 @@
+import { expect as baseExpect, } from "@playwright/test";
+/**
+ * Evaluate whether an element has the given state on its `elementInternals`
+ * property using the `:state()` pseudo-class.
+ *
+ * @param locator - The Playwright locator for the element.
+ * @param state - The name of the state.
+ * @param options - Optional timeout configuration.
+ */
+export async function toHaveCustomState(locator, state, options) {
+    const assertionName = "toHaveCustomState";
+    let pass;
+    let matcherResult;
+    const expected = !this.isNot;
+    try {
+        baseExpect(await locator.evaluate((el, state) => el.matches(`:state(${state})`), state, options)).toEqual(true);
+        pass = true;
+    }
+    catch (err) {
+        matcherResult = err.matcherResult;
+        pass = false;
+    }
+    const message = pass
+        ? () => this.utils.matcherHint(assertionName, undefined, undefined, {
+            isNot: this.isNot,
+        }) +
+            "\n\n" +
+            `Locator: ${locator}\n` +
+            `Expected: ${this.isNot ? "not" : ""}${this.utils.printExpected(expected)}\n` +
+            (matcherResult
+                ? `Received: ${this.utils.printReceived(matcherResult.actual)}`
+                : "")
+        : () => this.utils.matcherHint(assertionName, undefined, undefined, {
+            isNot: this.isNot,
+        }) +
+            "\n\n" +
+            `Locator: ${locator}\n` +
+            `Expected: ${this.utils.printExpected(expected)}\n` +
+            (matcherResult
+                ? `Received: ${this.utils.printReceived(matcherResult.actual)}`
+                : "");
+    return {
+        name: assertionName,
+        message,
+        pass,
+        expected,
+        actual: matcherResult?.actual,
+    };
+}

package/dist/esm/fixtures/csr-fixture.js

@@ -0,0 +1,153 @@
+/**
+ * A fixture for testing FAST components with Playwright.
+ */
+export class CSRFixture {
+    /**
+     * Creates an instance of the CSRFixture.
+     *
+     * @param page - The Playwright page object.
+     * @param tagName - The tag name of the custom element.
+     * @param innerHTML - The inner HTML of the custom element.
+     * @param waitFor - Additional custom elements to wait for.
+     */
+    constructor(page, tagName, innerHTML, waitFor = []) {
+        this.page = page;
+        this.tagName = tagName;
+        this.innerHTML = innerHTML;
+        this.element = this.page.locator(this.tagName);
+        this.waitFor = waitFor;
+    }
+    /**
+     * Adds a style tag to the page.
+     *
+     * @param options - The options for the style tag.
+     * @see {@link Page.addStyleTag}
+     */
+    async addStyleTag(options) {
+        await this.page.addStyleTag(options);
+    }
+    /**
+     * Navigates to the specified URL.
+     *
+     * @param url - The URL to navigate to. Defaults to "/".
+     */
+    async goto(url = "/") {
+        await this.page.goto(url);
+    }
+    /**
+     * Applies a set of design tokens as CSS custom properties on the body.
+     *
+     * @param tokens - A record mapping token names to values. Each key will
+     *   be prefixed with `--` and set as a CSS custom property.
+     */
+    async applyTokens(tokens) {
+        await this.page.evaluate(async (theme) => {
+            Object.entries(theme).forEach(([key, value]) => {
+                document.body.style.setProperty(`--${key}`, typeof value === "string" ? value : `${value}`);
+            });
+        }, tokens);
+    }
+    /**
+     * Generates the default template for the fixture.
+     */
+    defaultTemplate(tagName = this.tagName, attributes = {}, innerHTML = this.innerHTML) {
+        const attributesString = Object.entries(attributes)
+            .map(([key, value]) => {
+            if (value === true) {
+                return key;
+            }
+            return `${key}="${value.replace(/"/g, "")}"`;
+        })
+            .join(" ");
+        return `<${tagName} ${attributesString}>${innerHTML}</${tagName}>`;
+    }
+    /**
+     * Sets the template for the fixture's page.
+     *
+     * When `templateOrOptions` is an object, the method merges specific
+     * template options with values configured via the Playwright `test.use`
+     * configuration for the current test suite.
+     *
+     * If `templateOrOptions` is a string, it is treated as the complete HTML
+     * body for the fixture.
+     *
+     * If `templateOrOptions` is not provided, the method uses the default
+     * template based on the fixture's `tagName` and `innerHTML` properties.
+     *
+     * @param templateOrOptions - The template configuration.
+     */
+    async setTemplate(templateOrOptions) {
+        const template = typeof templateOrOptions === "string"
+            ? templateOrOptions
+            : this.defaultTemplate(this.tagName, templateOrOptions?.attributes, templateOrOptions?.innerHTML);
+        await this.page.locator("body").evaluate((node, template) => {
+            const fragment = document.createRange().createContextualFragment(template);
+            node.innerHTML = "";
+            node.append(fragment);
+        }, template);
+        if (this.tagName) {
+            await this.waitForStability();
+        }
+    }
+    /**
+     * Waits for the fixture to reach a stable state.
+     *
+     * This includes waiting for the custom element and any additional
+     * specified elements to be defined and for the body to become stable.
+     */
+    async waitForStability() {
+        if ((await this.element.count()) > 0) {
+            const elements = await this.page
+                .locator([this.tagName, ...this.waitFor].join(","))
+                .all();
+            await Promise.allSettled(elements.map(element => element.waitFor({
+                state: "attached",
+                timeout: 1000,
+            })));
+        }
+        await this.waitForCustomElement(this.tagName, ...this.waitFor);
+        await (await this.page.locator("body").elementHandle())?.waitForElementState("stable");
+    }
+    /**
+     * Updates the content of the fixture by modifying the specified
+     * element's attributes and/or inner HTML.
+     *
+     * @param locator - The locator or selector for the element to update.
+     * @param options - The options for updating the element.
+     */
+    async updateTemplate(locator, options) {
+        const element = typeof locator === "string" ? this.page.locator(locator) : locator;
+        await element.evaluate((node, options) => {
+            if (options.innerHTML !== undefined) {
+                node.innerHTML = options.innerHTML;
+            }
+            if (options.attributes) {
+                const attributesAsJSON = options.attributes;
+                Object.entries(attributesAsJSON).forEach(([key, value]) => {
+                    if (value === true) {
+                        node.setAttribute(key, "");
+                    }
+                    else if (value === false) {
+                        node.removeAttribute(key);
+                    }
+                    else if (typeof value === "string") {
+                        node.setAttribute(key, value);
+                    }
+                });
+            }
+        }, options);
+    }
+    /**
+     * Waits for the specified custom elements to be defined in the
+     * browser's CustomElementRegistry.
+     *
+     * @param tagName - The primary tag name to wait for.
+     * @param tagNames - Additional tag names to wait for.
+     */
+    async waitForCustomElement(tagName = this.tagName, ...tagNames) {
+        if (!tagName && !tagNames.length) {
+            return;
+        }
+        await this.page.waitForFunction((tagNames) => Promise.all(tagNames.map(t => customElements.whenDefined(t))), [tagName, ...tagNames]);
+    }
+}

package/dist/esm/fixtures/csr-fixture.pw.spec.js

@@ -0,0 +1,137 @@
+import { expect, test } from "@microsoft/fast-test-harness";
+test.describe("CSR: setTemplate", () => {
+    test.use({ tagName: "test-widget" });
+    test("should render the element with default options", async ({ fastPage }) => {
+        await fastPage.setTemplate();
+        await expect(fastPage.element).toHaveCount(1);
+    });
+    test("should render with innerHTML", async ({ fastPage }) => {
+        await fastPage.setTemplate({ innerHTML: "<span>child</span>" });
+        await expect(fastPage.element).toHaveCount(1);
+        await expect(fastPage.element).toContainText("child");
+    });
+    test("should render with attributes", async ({ fastPage }) => {
+        await fastPage.setTemplate({
+            attributes: { label: "Hello", size: "large" },
+        });
+        await expect(fastPage.element).toHaveAttribute("label", "Hello");
+        await expect(fastPage.element).toHaveAttribute("size", "large");
+    });
+    test("should render with boolean attribute", async ({ fastPage }) => {
+        await fastPage.setTemplate({ attributes: { disabled: true } });
+        await expect(fastPage.element).toHaveAttribute("disabled");
+    });
+    test("should render with a raw HTML string", async ({ fastPage }) => {
+        await fastPage.setTemplate(`<test-widget label="raw">raw content</test-widget>`);
+        await expect(fastPage.element).toHaveAttribute("label", "raw");
+        await expect(fastPage.element).toContainText("raw content");
+    });
+    test("should replace the previous template on subsequent calls", async ({ fastPage, }) => {
+        await fastPage.setTemplate({ attributes: { label: "first" } });
+        await expect(fastPage.element).toHaveAttribute("label", "first");
+        await fastPage.setTemplate({ attributes: { label: "second" } });
+        await expect(fastPage.element).toHaveAttribute("label", "second");
+        await expect(fastPage.element).toHaveCount(1);
+    });
+});
+test.describe("CSR: updateTemplate", () => {
+    test.use({ tagName: "test-widget" });
+    test("should update attributes on an existing element", async ({ fastPage }) => {
+        await fastPage.setTemplate({ attributes: { label: "before" } });
+        await expect(fastPage.element).toHaveAttribute("label", "before");
+        await fastPage.updateTemplate("test-widget", {
+            attributes: { label: "after" },
+        });
+        await expect(fastPage.element).toHaveAttribute("label", "after");
+    });
+    test("should remove an attribute when set to false", async ({ fastPage }) => {
+        await fastPage.setTemplate({ attributes: { disabled: true } });
+        await expect(fastPage.element).toHaveAttribute("disabled");
+        await fastPage.updateTemplate("test-widget", {
+            attributes: { disabled: false },
+        });
+        await expect(fastPage.element).not.toHaveAttribute("disabled");
+    });
+    test("should update innerHTML", async ({ fastPage }) => {
+        await fastPage.setTemplate({ innerHTML: "original" });
+        await fastPage.updateTemplate("test-widget", {
+            innerHTML: "updated",
+        });
+        await expect(fastPage.element).toContainText("updated");
+    });
+    test("should accept a Locator", async ({ fastPage }) => {
+        await fastPage.setTemplate({ attributes: { label: "loc" } });
+        await fastPage.updateTemplate(fastPage.element, {
+            attributes: { label: "via-locator" },
+        });
+        await expect(fastPage.element).toHaveAttribute("label", "via-locator");
+    });
+});
+test.describe("CSR: applyTokens", () => {
+    test.use({ tagName: "test-widget" });
+    test("should set CSS custom properties on the body", async ({ fastPage }) => {
+        await fastPage.setTemplate();
+        await fastPage.applyTokens({
+            "color-primary": "#0078d4",
+            "spacing-m": "8px",
+        });
+        const value = await fastPage.page.evaluate(() => document.body.style.getPropertyValue("--color-primary"));
+        expect(value).toBe("#0078d4");
+    });
+});
+test.describe("CSR: waitForCustomElement", () => {
+    test.use({ tagName: "test-widget" });
+    test("should resolve for a registered element", async ({ fastPage }) => {
+        await fastPage.setTemplate();
+        await fastPage.waitForCustomElement("test-widget");
+    });
+});
+test.describe("CSR: toHaveCustomState", () => {
+    test.use({ tagName: "test-widget" });
+    test("should pass when element has the custom state", async ({ fastPage }) => {
+        await fastPage.setTemplate({ attributes: { disabled: true } });
+        await expect(fastPage.element).toHaveCustomState("disabled");
+    });
+    test("should fail (negated) when element does not have the state", async ({ fastPage, }) => {
+        await fastPage.setTemplate();
+        await expect(fastPage.element).not.toHaveCustomState("disabled");
+    });
+});
+test.describe("CSR: element locator", () => {
+    test.use({ tagName: "test-widget" });
+    test("should locate the element by tag name", async ({ fastPage }) => {
+        await fastPage.setTemplate();
+        await expect(fastPage.element).toHaveCount(1);
+    });
+});
+test.describe("CSR: addStyleTag", () => {
+    test.use({ tagName: "test-widget" });
+    test("should add a style tag with content", async ({ fastPage }) => {
+        await fastPage.setTemplate();
+        await fastPage.addStyleTag({
+            content: "test-widget { border: 1px solid red; }",
+        });
+        const hasBorder = await fastPage.page.evaluate(() => {
+            const styles = document.querySelectorAll("style");
+            return Array.from(styles).some(s => s.textContent?.includes("border: 1px solid red"));
+        });
+        expect(hasBorder).toBe(true);
+    });
+});
+test.describe("CSR: multiple elements", () => {
+    test.use({ tagName: "test-widget" });
+    test("should handle templates with multiple instances", async ({ fastPage }) => {
+        await fastPage.setTemplate(`
+            <test-widget label="first">one</test-widget>
+            <test-widget label="second">two</test-widget>
+        `);
+        await expect(fastPage.element).toHaveCount(2);
+    });
+});
+test.describe("CSR: waitFor", () => {
+    test.use({ tagName: "test-widget", waitFor: ["test-widget"] });
+    test("should wait for additional elements specified in waitFor", async ({ fastPage, }) => {
+        await fastPage.setTemplate();
+        await expect(fastPage.element).toHaveCount(1);
+    });
+});

package/dist/esm/fixtures/index.js

@@ -0,0 +1,48 @@
+import { expect as baseExpect, test as baseTest } from "@playwright/test";
+import { toHaveCustomState } from "./assertions.js";
+import { CSRFixture } from "./csr-fixture.js";
+import { SSRFixture } from "./ssr-fixture.js";
+const isSSR = process.env.PLAYWRIGHT_TEST_SSR === "true";
+export const test = baseTest.extend({
+    /**
+     * The inner HTML to set on the fixture's custom element. This can be used
+     * to provide slotted content or otherwise customize the fixture's template.
+     */
+    innerHTML: ["", { option: true }],
+    /**
+     * The tag name of the custom element to test. This is used to construct the
+     * fixture's template and to determine when the page has finished loading.
+     */
+    tagName: ["", { option: true }],
+    /**
+     * Additional custom elements to wait for before running the test.
+     */
+    waitFor: [[], { option: true }],
+    /**
+     * Indicates if the test is running in SSR mode. When `true`, the fixture
+     * uses the `SSRFixture` class, which generates server-rendered fixtures.
+     *
+     * This can be set directly in a fixture via `test.use({ ssr: true })`, or
+     * indirectly with the environment variable `PLAYWRIGHT_TEST_SSR=true`.
+     */
+    ssr: [!!isSSR, { option: true }],
+    async fastPage({ page, innerHTML, ssr, tagName, waitFor }, use, testInfo) {
+        const testId = testInfo.titlePath
+            .join("-")
+            .replace(/[^a-z0-9-]/gi, "_")
+            .toLowerCase();
+        const testTitle = ssr ? `${testInfo.titlePath.join(" › ")}` : undefined;
+        const fastPage = ssr
+            ? new SSRFixture(page, tagName, innerHTML, waitFor, testId, testTitle)
+            : new CSRFixture(page, tagName, innerHTML, waitFor);
+        if (!ssr) {
+            await fastPage.goto();
+            await page.emulateMedia({ reducedMotion: "reduce" });
+            await fastPage.waitForCustomElement(tagName, ...waitFor);
+        }
+        await use(fastPage);
+    },
+});
+export const expect = baseExpect.extend({
+    toHaveCustomState,
+});

package/dist/esm/fixtures/ssr-fixture.js

@@ -0,0 +1,113 @@
+import { CSRFixture } from "./csr-fixture.js";
+export class SSRFixture extends CSRFixture {
+    constructor(page, tagName, innerHTML = "", waitFor = [], testId, testTitle) {
+        super(page, tagName, innerHTML, waitFor);
+        this.testId = testId;
+        this.testTitle = testTitle;
+        /**
+         * Styles buffered before {@link setTemplate} is called.
+         */
+        this.pendingStyles = [];
+        /**
+         * Whether the template has been rendered.
+         */
+        this.templateRendered = false;
+    }
+    /**
+     * Buffers style tags added before {@link setTemplate} so they can be
+     * included in the generated SSR page. After the template has been
+     * rendered, calls pass through to the page directly.
+     *
+     * @param options - The options for the style tag.
+     * @see {@link Page.addStyleTag}
+     */
+    async addStyleTag(options) {
+        if (this.templateRendered) {
+            await this.page.addStyleTag(options);
+            return;
+        }
+        this.pendingStyles.push(options);
+    }
+    /**
+     * Sets up the test fixture by posting the template or configuration
+     * to the SSR generation endpoint.
+     *
+     * This method constructs a request body based on the provided
+     * `templateOrOptions` and the current test context (like `testId`
+     * and `testTitle`). It sends this data to the `/generate-fixture`
+     * endpoint to create a server-side rendered fixture, navigates the
+     * page to the resulting URL, and waits for the page to stabilize.
+     *
+     * @param templateOrOptions - The template configuration.
+     */
+    async setTemplate(templateOrOptions) {
+        const body = {};
+        if (this.testId) {
+            body.testId = this.testId;
+            body.testTitle = this.testTitle || this.formatTestTitle(this.testId);
+        }
+        if (typeof templateOrOptions === "string") {
+            body.html = templateOrOptions.trim();
+        }
+        if (typeof templateOrOptions === "object") {
+            if (typeof templateOrOptions.innerHTML === "string") {
+                body.innerHTML = templateOrOptions.innerHTML;
+            }
+            if (templateOrOptions.attributes) {
+                const cleanedAttributes = {};
+                Object.entries(templateOrOptions.attributes).forEach(([key, value]) => {
+                    cleanedAttributes[key.trim()] =
+                        typeof value === "string" ? value.trim() : value;
+                });
+                body.attributes = JSON.stringify(cleanedAttributes);
+            }
+        }
+        if (!body.html && typeof templateOrOptions !== "string") {
+            body.tagName = this.tagName;
+            if (!body.innerHTML && typeof templateOrOptions?.innerHTML !== "string") {
+                body.innerHTML = this.innerHTML;
+            }
+        }
+        Object.entries(body).forEach(([key, value]) => {
+            if (typeof value === "string") {
+                body[key] = value.replace(/\s+/g, " ").trim();
+            }
+        });
+        if (this.pendingStyles.length) {
+            body.styles = JSON.stringify(this.pendingStyles.map(s => s?.content).filter((c) => !!c));
+        }
+        const response = await this.page.request.post("/generate-fixture", {
+            data: body,
+        });
+        if (!response.ok()) {
+            throw new Error(`Failed to generate fixture: ${response.status()} ${response.statusText()}`);
+        }
+        const result = await response.json();
+        if (!result.url) {
+            throw new Error(`Invalid response from server: ${JSON.stringify(result)}`);
+        }
+        await this.page.goto(result.url);
+        await this.waitForStability();
+        this.templateRendered = true;
+        this.pendingStyles.length = 0;
+    }
+    /**
+     * Formats the test title based on the provided test ID.
+     */
+    formatTestTitle(testId) {
+        const match = testId.match(/^(.*?\.(ts|js))-(.+)$/);
+        if (!match) {
+            return testId
+                .split("_")
+                .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+                .join(" ");
+        }
+        const filePath = match[1];
+        const testParts = match[3];
+        const sections = testParts.split("-").map(section => section
+            .split("_")
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(" "));
+        return `${sections.join(" › ")} (${filePath})`;
+    }
+}