@microsoft/fast-test-harness 0.1.0

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

@@ -0,0 +1,189 @@
+import { expect, test } from "@microsoft/fast-test-harness";
+test.describe("SSR: setTemplate", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    test("should navigate to the SSR fixture page", async ({ fastPage, page }) => {
+        await fastPage.setTemplate();
+        const url = new URL(page.url());
+        expect(url.pathname).toMatch(/^\/ssr-.*\.html$/);
+        expect(url.pathname).toContain("should_navigate_to_the_ssr_fixture_page");
+    });
+    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("SSR: updateTemplate", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    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("SSR: applyTokens", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    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("SSR: waitForCustomElement", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    test("should resolve for a registered element", async ({ fastPage }) => {
+        await fastPage.setTemplate();
+        await fastPage.waitForCustomElement("test-widget");
+    });
+});
+test.describe("SSR: toHaveCustomState", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    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("SSR: element locator", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    test("should locate the element by tag name", async ({ fastPage }) => {
+        await fastPage.setTemplate();
+        await expect(fastPage.element).toHaveCount(1);
+    });
+});
+test.describe("SSR: declarative shadow DOM", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    test("should have a shadow root after SSR render", async ({ fastPage }) => {
+        await fastPage.setTemplate({ attributes: { label: "DSD" } });
+        const hasShadow = await fastPage.element.evaluate(el => el.shadowRoot !== null);
+        expect(hasShadow).toBe(true);
+    });
+});
+test.describe("SSR: template placeholder replacement", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    test("should replace the fixture placeholder with rendered component HTML", async ({ fastPage, page, }) => {
+        await fastPage.setTemplate({ attributes: { label: "test" } });
+        const bodyHtml = await page.locator("body").innerHTML();
+        expect(bodyHtml).not.toContain("<!--fixture-->");
+        expect(bodyHtml).toContain("<test-widget");
+    });
+    test("should replace the title placeholder with the test title", async ({ fastPage, page, }) => {
+        await fastPage.setTemplate();
+        const title = await page.title();
+        expect(title).not.toBe("<!--fixturetitle-->");
+        expect(title.length).toBeGreaterThan(0);
+    });
+    test("should replace the templates placeholder with template content", async ({ fastPage, page, }) => {
+        await fastPage.setTemplate();
+        const bodyHtml = await page.locator("body").innerHTML();
+        expect(bodyHtml).not.toContain("<!--templates-->");
+    });
+    test("should replace the stylespreload placeholder with preload links", async ({ fastPage, page, }) => {
+        await fastPage.setTemplate();
+        const headHtml = await page.locator("head").innerHTML();
+        expect(headHtml).not.toContain("<!--stylespreload-->");
+        expect(headHtml).toContain("/test-theme.css");
+    });
+    test("should not contain any unreplaced placeholder comments", async ({ fastPage, page, }) => {
+        await fastPage.setTemplate();
+        const fullHtml = await page.content();
+        expect(fullHtml).not.toContain("<!--fixture-->");
+        expect(fullHtml).not.toContain("<!--fixturetitle-->");
+        expect(fullHtml).not.toContain("<!--templates-->");
+        expect(fullHtml).not.toContain("<!--stylespreload-->");
+    });
+});
+test.describe("SSR: addStyleTag buffering", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    test("should include buffered styles in the SSR page", async ({ fastPage, page }) => {
+        await fastPage.addStyleTag({
+            content: "test-widget { outline: 3px solid blue; }",
+        });
+        await fastPage.setTemplate();
+        const hasStyle = await page.evaluate(() => {
+            const styles = document.querySelectorAll("style");
+            return Array.from(styles).some(s => s.textContent?.includes("outline: 3px solid blue"));
+        });
+        expect(hasStyle).toBe(true);
+    });
+    test("should pass through addStyleTag calls after setTemplate", async ({ fastPage, page, }) => {
+        await fastPage.setTemplate();
+        await fastPage.addStyleTag({
+            content: "test-widget { margin: 99px; }",
+        });
+        const hasStyle = await page.evaluate(() => {
+            const styles = document.querySelectorAll("style");
+            return Array.from(styles).some(s => s.textContent?.includes("margin: 99px"));
+        });
+        expect(hasStyle).toBe(true);
+    });
+});
+test.describe("SSR: multiple elements", () => {
+    test.use({ tagName: "test-widget", ssr: true });
+    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);
+    });
+});

package/dist/esm/index.js

@@ -0,0 +1,6 @@
+export { installDomShim } from "./build/dom-shim.js";
+export { toHaveCustomState } from "./fixtures/assertions.js";
+export { CSRFixture, } from "./fixtures/csr-fixture.js";
+export { expect, test } from "./fixtures/index.js";
+export { SSRFixture } from "./fixtures/ssr-fixture.js";
+export { createSSRRenderer, } from "./ssr/render.js";

package/dist/esm/ssr/entry-client.js

@@ -0,0 +1,2 @@
+import { TemplateElement } from "@microsoft/fast-html";
+TemplateElement.define({ name: "f-template" });

package/dist/esm/ssr/render.js

@@ -0,0 +1,381 @@
+/**
+ * SSR rendering powered by `@microsoft/fast-build`'s WASM renderer.
+ *
+ * Provides a high-level `createSSRRenderer()` factory that scans for
+ * component build artifacts (f-templates, stylesheets) and returns a
+ * `render()` function compatible with the test harness server's
+ * `entry-server.ts` contract.
+ *
+ * Supports two layout modes:
+ *
+ * **Multi-component package**: one package contains all
+ * components in subdirectories.
+ * ```ts
+ * const { render } = createSSRRenderer({
+ *     packageName: "@fluentui/web-components",
+ *     tagPrefix: "fluent",
+ * });
+ * ```
+ *
+ * **Per-component packages**: each component is a separate npm package with
+ * flat exports.
+ * ```ts
+ * const { render } = createSSRRenderer({
+ *     tagPrefix: "mai",
+ *     components: [
+ *         { name: "button", packageName: "@mai-ui/button" },
+ *         { name: "checkbox", packageName: "@mai-ui/checkbox" },
+ *     ],
+ * });
+ * ```
+ */
+import { globSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Try to load the `@microsoft/fast-build` WASM module. Returns `null`
+ * if the package is not installed.
+ */
+function loadWasm() {
+    try {
+        // The WASM module is CJS and must be loaded synchronously.
+        // Use a targeted createRequire anchored to this module so it
+        // resolves from the harness's own dependencies.
+        return createRequire(import.meta.url)("@microsoft/fast-build/wasm/microsoft_fast_build.js");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a file from a package export. Returns the absolute path or null.
+ */
+function resolveSpecifier(specifier) {
+    try {
+        return fileURLToPath(import.meta.resolve(specifier));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a package root directory from its package.json export.
+ */
+function resolvePackageRoot(packageName) {
+    return dirname(fileURLToPath(import.meta.resolve(`${packageName}/package.json`)));
+}
+/**
+ * Convert an absolute path to a server-relative URL.
+ */
+function toServerUrl(absolutePath, packageRoot) {
+    return `/${relative(packageRoot, absolutePath).replace(/\\/g, "/")}`;
+}
+/**
+ * Parse a JavaScript default value string from CEM into a JSON-safe value.
+ * @internal
+ */
+export function parseDefaultValue(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || trimmed === "undefined" || trimmed === "null") {
+        return "";
+    }
+    if (trimmed === "true") {
+        return true;
+    }
+    if (trimmed === "false") {
+        return false;
+    }
+    if (trimmed.startsWith("'") || trimmed.startsWith('"')) {
+        return trimmed.slice(1, -1);
+    }
+    const num = Number(trimmed);
+    if (!Number.isNaN(num)) {
+        return num;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Load a Custom Elements Manifest and extract default state for
+ * each custom element declaration. Returns a map of tag names to
+ * their default property values.
+ */
+function loadDefaultStateFromCEM(packageName, tagPrefix) {
+    const cemPath = resolveSpecifier(`${packageName}/custom-elements.json`);
+    if (!cemPath) {
+        return new Map();
+    }
+    try {
+        const cem = JSON.parse(readFileSync(cemPath, "utf8"));
+        const result = new Map();
+        for (const mod of cem.modules ?? []) {
+            for (const decl of mod.declarations ?? []) {
+                if (!decl.customElement) {
+                    continue;
+                }
+                const tagName = decl.tagName ?? `${tagPrefix}-${decl.name?.toLowerCase()}`;
+                const state = {};
+                for (const member of decl.members ?? []) {
+                    if (member.kind !== "field" || member.privacy !== "public") {
+                        continue;
+                    }
+                    state[member.name] =
+                        member.default != null
+                            ? parseDefaultValue(String(member.default))
+                            : "";
+                }
+                if (Object.keys(state).length > 0) {
+                    result.set(tagName, state);
+                }
+            }
+        }
+        return result;
+    }
+    catch {
+        return new Map();
+    }
+}
+/**
+ * Load artifacts for a component from a monolithic package
+ * (e.g., `@fluentui/web-components/button/template.html`).
+ */
+function loadMonolithicComponent(packageName, componentDir, packageRoot) {
+    const fTemplatePath = resolveSpecifier(`${packageName}/${componentDir}/template.html`);
+    const stylesPath = resolveSpecifier(`${packageName}/${componentDir}/styles.css`);
+    return {
+        componentName: componentDir,
+        fTemplate: fTemplatePath ? readFileSync(fTemplatePath, "utf8") : null,
+        stylesUrl: stylesPath ? toServerUrl(stylesPath, packageRoot) : "",
+    };
+}
+/**
+ * Load artifacts for a component from a per-component package
+ * (e.g., `@mai-ui/button/template.html`).
+ */
+function loadPerPackageComponent(reg) {
+    const fTemplatePath = resolveSpecifier(`${reg.packageName}/template.html`);
+    return {
+        componentName: reg.name,
+        fTemplate: fTemplatePath ? readFileSync(fTemplatePath, "utf8") : null,
+        stylesUrl: `${reg.packageName}/styles.css`,
+    };
+}
+/**
+ * Replace the `{{styles}}` placeholder in an f-template with a
+ * stylesheet `<link>` tag. Falls back to injecting after the opening
+ * `<template>` tag if the placeholder is absent.
+ * @internal
+ */
+export function renderTemplate(rawTemplate, styles) {
+    if (!styles) {
+        return rawTemplate.replace("{{styles}}", "");
+    }
+    const link = `<link rel="stylesheet" href="${styles}">`;
+    const template = rawTemplate.replace("{{styles}}", link);
+    if (template === rawTemplate) {
+        return template.replace(/(<template[^>]*>)/i, match => `${match}${link}`);
+    }
+    return template;
+}
+/**
+ * Build the entry HTML that the WASM renderer processes.
+ * Constructs either a raw HTML fixture or a single custom element
+ * from the query parameters.
+ * @internal
+ */
+export function buildEntryHtml(queryObj) {
+    if ("html" in queryObj) {
+        return String(queryObj.html);
+    }
+    const tagName = String(queryObj.tagName ?? "");
+    if (!tagName) {
+        return "";
+    }
+    let attributes = {};
+    if (queryObj.attributes) {
+        try {
+            attributes =
+                typeof queryObj.attributes === "string"
+                    ? JSON.parse(queryObj.attributes)
+                    : queryObj.attributes;
+        }
+        catch {
+            // Ignore invalid JSON.
+        }
+    }
+    const innerHTML = queryObj.innerHTML ? String(queryObj.innerHTML) : "";
+    const attrs = Object.entries(attributes)
+        .filter(([, value]) => value !== false && value != null)
+        .map(([key, value]) => {
+        if (value === true) {
+            return key;
+        }
+        const escaped = String(value)
+            .replace(/&/g, "&amp;")
+            .replace(/"/g, "&quot;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;");
+        return `${key}="${escaped}"`;
+    })
+        .join(" ");
+    return `<${tagName}${attrs ? ` ${attrs}` : ""}>${innerHTML}</${tagName}>`;
+}
+/**
+ * Build the state JSON for the WASM renderer from the query
+ * parameters. Includes attribute values and normalised (hyphen-
+ * stripped) variants so bindings like `{{arialabel}}` resolve for
+ * an `aria-label` HTML attribute.
+ * @internal
+ */
+export function buildState(queryObj) {
+    let attributes = {};
+    if (queryObj.attributes) {
+        try {
+            attributes =
+                typeof queryObj.attributes === "string"
+                    ? JSON.parse(queryObj.attributes)
+                    : queryObj.attributes;
+        }
+        catch {
+            // Ignore invalid JSON.
+        }
+    }
+    const state = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        state[key] = value;
+        const stripped = key.replace(/-/g, "");
+        if (stripped !== key) {
+            state[stripped] = value;
+        }
+    }
+    return state;
+}
+/**
+ * Create an SSR renderer that uses `@microsoft/fast-build`'s WASM
+ * module to render f-templates into declarative shadow DOM on each
+ * request, with full expression evaluation and nested component
+ * support.
+ *
+ * Supports two modes:
+ * - **`packageName`**: Scans a monolithic package's dist directory for
+ *   components in subdirectories (Fluent-style).
+ * - **`components`**: Uses an explicit list of per-component packages
+ *   with flat exports (MAI-style).
+ */
+export function createSSRRenderer(options) {
+    const { tagPrefix } = options;
+    if (options.components && options.packageName) {
+        throw new Error("createSSRRenderer: 'components' and 'packageName' are mutually exclusive. " +
+            "Provide one or the other, not both.");
+    }
+    const wasm = loadWasm();
+    if (!wasm) {
+        throw new Error("@microsoft/fast-build is required for SSR rendering. " +
+            "Install it as a dependency to enable WASM-based template rendering.");
+    }
+    // Maps keyed by component name (e.g., "button").
+    const fTemplatesByName = new Map();
+    const styleUrlsByName = new Map();
+    // Collect component artifacts from either mode.
+    const artifacts = [];
+    if (options.components) {
+        // Per-component packages (MAI-style).
+        for (const reg of options.components) {
+            artifacts.push(loadPerPackageComponent(reg));
+        }
+    }
+    else if (options.packageName) {
+        // Monolithic package (Fluent-style).
+        const packageRoot = resolvePackageRoot(options.packageName);
+        const distDir = join(packageRoot, options.distDir ?? "dist/esm");
+        const pattern = "**/*.template.html";
+        for (const templatePath of globSync(pattern, { cwd: distDir })) {
+            if (templatePath.includes("template-dsd") ||
+                templatePath.includes("template-webui")) {
+                continue;
+            }
+            const componentDir = dirname(templatePath).replace(/\\/g, "/");
+            if (componentDir === ".") {
+                continue;
+            }
+            artifacts.push(loadMonolithicComponent(options.packageName, componentDir, packageRoot));
+        }
+    }
+    // Populate maps and collect default state from CEM.
+    const defaultStateByTag = new Map();
+    for (const art of artifacts) {
+        const tagName = `${tagPrefix}-${art.componentName}`;
+        if (art.fTemplate) {
+            fTemplatesByName.set(art.componentName, art.fTemplate);
+        }
+        styleUrlsByName.set(art.componentName, art.stylesUrl);
+    }
+    // Load CEM defaults per-package (each package may contain multiple elements).
+    if (options.components) {
+        for (const reg of options.components) {
+            const cemDefaults = loadDefaultStateFromCEM(reg.packageName, tagPrefix);
+            for (const [tag, state] of cemDefaults) {
+                defaultStateByTag.set(tag, state);
+            }
+        }
+    }
+    else if (options.packageName) {
+        const cemDefaults = loadDefaultStateFromCEM(options.packageName, tagPrefix);
+        for (const [tag, state] of cemDefaults) {
+            defaultStateByTag.set(tag, state);
+        }
+    }
+    // Inject styles into f-templates, then parse into the WASM
+    // templates map (tag-name → inner template content).
+    const templatesMap = {};
+    for (const [name, fTemplate] of fTemplatesByName) {
+        const styled = renderTemplate(fTemplate, styleUrlsByName.get(name) ?? "");
+        fTemplatesByName.set(name, styled);
+        const parsed = JSON.parse(wasm.parse_f_templates(styled));
+        const entry = parsed.find((t) => t.name !== null);
+        if (entry) {
+            templatesMap[`${tagPrefix}-${name}`] = entry.content;
+        }
+        else {
+            console.warn(`No named template found for ${tagPrefix}-${name}`);
+        }
+    }
+    const templatesJson = JSON.stringify(templatesMap);
+    // Concatenate all f-templates (with styles) for client hydration.
+    const allFTemplates = [...fTemplatesByName.values()].join("\n");
+    // Resolve theme stylesheet if provided.
+    let preloadLinks = "";
+    if (options.themeStylesheet) {
+        preloadLinks = `<link rel="stylesheet" href="${options.themeStylesheet}">`;
+    }
+    return {
+        render(queryObj = {}) {
+            const entryHtml = buildEntryHtml(queryObj);
+            const requestState = buildState(queryObj);
+            // Merge CEM default state (base) with request state (overrides).
+            const tagName = String(queryObj.tagName ?? "");
+            const defaults = defaultStateByTag.get(tagName) ?? {};
+            const state = { ...defaults, ...requestState };
+            let fixture = "";
+            if (entryHtml) {
+                try {
+                    const rendered = wasm.render_entry_with_templates(`<html><body>${entryHtml}</body></html>`, templatesJson, JSON.stringify(state), "camelCase");
+                    // Extract body content from the rendered document.
+                    const bodyMatch = rendered.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+                    fixture = bodyMatch?.[1] ?? entryHtml;
+                }
+                catch (e) {
+                    // Fall back to the raw entry HTML if rendering fails.
+                    console.error("WASM render failed:", e);
+                    fixture = entryHtml;
+                }
+            }
+            return { template: allFTemplates, fixture, preloadLinks };
+        },
+    };
+}