pcbjam/tests/kicad/occ-export.spec.ts

import type { Page } from '@playwright/test';
import * as fs from 'fs';
import * as path from 'path';
import { test, expect } from './fixtures';
import { waitForEditorReady, stableShot, settledShot } from '../e2e/utils/element-tracker';
import { injectFromSubmodule } from './utils/fs-inject';
import { openBoardProgrammatically } from './utils/board-ready';
import { findWxButton, clickWxButton, openStepExportDialog, dismissReportDialog } from './utils/wx-dialogs';

/**
 * STEP export through the occ_service worker (docs/features/occ-split/):
 * pcbnew.wasm carries no OCC — DIALOG_EXPORT_STEP's browser branch runs
 * EXPORTER_STEP, whose WASM shadow suspends via EM_ASYNC_JS and hands the
 * job to `globalThis.occService` (worker with its own OCC-linked module).
 *
 * Asserted end to end:
 *   1. occ_service.{js,wasm} is NOT fetched at boot or board load — only the
 *      export click triggers it (the lazy-load boundary).
 *   2. The (unchanged) export dialog drives the whole chain: menu → dialog →
 *      Export button → worker → STEP bytes.
 *   3. The result is a real STEP file (ISO-10303-21 magic, non-trivial size),
 *      captured by the provider stub where the app would download it.
 */

const KICAD_VERSION_DIR = '10.0';
const PROJECT_DIR_MEMFS = `/home/kicad/documents/kicad/${KICAD_VERSION_DIR}/projects`;

const DEMO = { name: 'pic_programmer', dir: 'pic_programmer', stem: 'pic_programmer' } as const;

async function loadBoard(page: Page, testLogger: { consoleLogs: string[]; errors: string[] }): Promise<void> {
    const pcbFilename = `${DEMO.stem}.kicad_pcb`;
    const proFilename = `${DEMO.stem}.kicad_pro`;

    await injectFromSubmodule(page, `kicad/demos/${DEMO.dir}/${pcbFilename}`,
        `${PROJECT_DIR_MEMFS}/${pcbFilename}`);
    await injectFromSubmodule(page, `kicad/demos/${DEMO.dir}/${proFilename}`,
        `${PROJECT_DIR_MEMFS}/${proFilename}`);

    const result = await openBoardProgrammatically(
        page,
        `${PROJECT_DIR_MEMFS}/${pcbFilename}`,
        DEMO.stem,
        testLogger,
        60000,
    );
    console.log(`[TEST] ${DEMO.name} board-ready result: ${result}`);
}

test.describe('OCC export via occ_service worker', () => {
    test.describe.configure({ mode: 'serial' });
    test.setTimeout(240000);

    test('export dialog produces a valid STEP; occ_service fetches lazily', async ({ page, testLogger }) => {
        // Track occ_service fetches from the very start — the lazy boundary is
        // the core assertion.
        const occFetches: string[] = [];
        page.on('request', (r) => {
            if (r.url().includes('occ_service')) occFetches.push(r.url());
        });

        await page.goto('/kicad/pcbnew.html');
        await waitForEditorReady(page);
        await loadBoard(page, testLogger);
        // Board-loaded ≠ board-painted: once the export dialog's modal pump takes
        // over, the GAL may never repaint behind it — whichever paint state the
        // canvas had at menu-open time is what the dialog screenshots freeze.
        // Settle the pixels first so occ-export-{dialog,done}.png always capture
        // the painted board (this bistability flagged occ-export-done between two
        // identical-code CI runs).
        await settledShot(page.locator('#canvas'), expect);

        expect(occFetches, 'occ_service must NOT be fetched before the export').toHaveLength(0);

        // File → Export → STEP/GLB/… and the unchanged export dialog.
        await openStepExportDialog(page);
        await stableShot(page, 'occ-export-dialog.png');

        expect(await clickWxButton(page, 'Export'), 'Export button click').toBe(true);

        // The provider stub captures the bytes where the app would download.
        await page.waitForFunction(
            () => ((window as any).__occExports?.length ?? 0) > 0,
            null, { timeout: 180000 });

        const exports = await page.evaluate(() => (window as any).__occExports as Array<{
            name: string; size: number; magic: string;
        }>);
        console.log(`[TEST] captured exports: ${JSON.stringify(exports)}`);

        expect(exports).toHaveLength(1);
        expect(exports[0].name, 'download name comes from the dialog')
            .toMatch(/\.step$/i);
        expect(exports[0].magic.startsWith('ISO-10303-21'), 'STEP magic').toBe(true);
        expect(exports[0].size, 'non-trivial STEP body').toBeGreaterThan(10_000);

        expect(occFetches.length, 'occ_service was fetched lazily by the export')
            .toBeGreaterThan(0);

        // Dismiss the "Export complete" report dialog: it opens on top of the
        // export dialog's modal lease (1 → 2), which IS its observable signal.
        await dismissReportDialog(page, 1, 'export complete');

        await stableShot(page, 'occ-export-done.png');
    });

    test('worker decode fault settles concurrent native wait and the next export recovers', async ({ page, testLogger }) => {
        await page.goto('/kicad/pcbnew.html');
        await waitForEditorReady(page);
        await loadBoard(page, testLogger);
        // The exact open Promise and title/paint helper have completed. Keep a
        // byte-stable baseline before opening a nested submenu.
        await settledShot(page.locator('#canvas'), expect);
        await openStepExportDialog(page);

        const probeBoard = fs.readFileSync(
            path.resolve(__dirname, '..', 'fixtures', 'demo', 'demo.kicad_pcb'),
            'utf8',
        );

        // Start one direct service request before the dialog's native request.
        // Both wait on the same lazy worker boot, then both post without a host
        // mutex. The harness injects a messageerror only when both are in the
        // generation's pending map, and the real worker is then terminated.
        await page.evaluate((boardText: string) => {
            const runtime = globalThis as any;
            runtime.__occServiceTestHooks.messageErrorWhenPendingAtLeast(2);
            runtime.__occParallelResult = null;
            void runtime.occService.request({
                kind: 'export',
                board: new TextEncoder().encode(boardText),
                jobJson: JSON.stringify({ format: 'step', export_components: false }),
                fileName: 'parallel-probe.step',
            }).then((res: unknown) => { runtime.__occParallelResult = res; });
        }, probeBoard);

        expect(await clickWxButton(page, 'Export'), 'first native Export button click').toBe(true);

        await page.waitForFunction(
            () => (globalThis as any).__occParallelResult !== null,
            null,
            { timeout: 30000 },
        );
        const parallelResult = await page.evaluate(
            () => (globalThis as any).__occParallelResult as { ok: boolean; report?: string },
        );
        expect(parallelResult.ok, 'the parallel request must settle on generation failure').toBe(false);
        expect(parallelResult.report, 'the exact messageerror reason reaches the caller')
            .toContain('message decode failed');

        // The C++ Export() request was the second request in the same failed
        // generation. Its exact wx wait must close and show the native failure
        // dialog instead of leaving the export handler parked.
        await page.waitForFunction(() => {
            const registry = window.wxElementRegistry;
            if (!registry) return false;
            const dialogs = registry.findAll({ visible: true })
                .filter((el) => /Dialog/.test(el.typeName ?? ''));
            return dialogs.length >= 2;
        }, null, { timeout: 30000 });
        await expect.poll(
            () => page.evaluate(() => {
                const scheduler = (globalThis as any).__wxScheduler;
                return scheduler?.pendingWaits?.('occ') ?? -1;
            }),
            { message: 'the native OCC wait must be completed by fail-all', timeout: 10000 },
        ).toBe(0);

        const failed = await page.evaluate(() => {
            const runtime = globalThis as any;
            const rendered = runtime.wxElementRegistry?.findAllRendered?.({}) ?? [];
            return {
                labels: rendered.map((el: any) => el.label ?? el.text ?? '').filter(Boolean),
                service: runtime.__occServiceTestHooks.snapshot(),
            };
        });
        expect(failed.service.maxPending,
            'two requests must coexist in one generation; worker requests are not serialized')
            .toBeGreaterThanOrEqual(2);
        expect(failed.service.requestsPosted,
            'every provider entry must reach the real worker transport')
            .toBe(failed.service.requestsStarted);
        expect(failed.service.workerGenerationsStarted,
            'the two parallel requests must share one worker generation').toHaveLength(1);
        expect(failed.service.pending, 'fail-all must drain the failed generation').toBe(0);
        expect(failed.service.retiredGenerations, 'the shared generation must be retired')
            .toContain(failed.service.workerGenerationsStarted[0]);
        expect(failed.service.activeGeneration, 'the failed slot must be cleared').toBeNull();
        expect(failed.service.armed, 'the one-shot fault must be consumed').toBe(false);
        console.log(`[TEST-OCC] native fault dialog labels: ${JSON.stringify(failed.labels)}`);

        // Resolve the parent action before dismissing the child, then reuse its
        // exact DOM identity. This prevents a label/geometry re-query from
        // turning the handback race into a click on some replacement control.
        const retryExport = await findWxButton(page, 'Export');
        expect(retryExport, 'the original parent Export button must remain registered').not.toBeNull();
        expect(retryExport!.x, 'the retry target has stable geometry').toBeGreaterThan(0);
        expect(retryExport!.y, 'the retry target has stable geometry').toBeGreaterThan(0);

        expect(await clickWxButton(page, 'OK'), 'dismiss native export failure').toBe(true);

        // page.mouse.click() completes when the browser has delivered the OK
        // input, not when the nested native modal has unwound.  The parent
        // export dialog is intentionally non-interactive until that exact
        // child lease closes.  Wait for the scheduler's observable modal
        // count to return from {export + failure} to {export} before clicking
        // through to the parent.
        await expect.poll(
            () => page.evaluate(() => {
                const scheduler = (globalThis as any).__wxScheduler;
                return scheduler?.pendingWaits?.('modal') ?? -1;
            }),
            { message: 'the failure child must retire before retrying its parent', timeout: 10000 },
        ).toBe(1);

        // The export dialog remains open. Its next request must create a fresh
        // generation and complete through the actual OCC module. Reuse the
        // captured geometry so a re-query can't land on a replacement control.
        if (!retryExport) throw new Error('parent Export button disappeared before retry');
        await page.mouse.click(retryExport.x, retryExport.y);
        await expect.poll(
            () => page.evaluate(() => (globalThis as any)
                .__occServiceTestHooks.snapshot().requestsStarted),
            {
                message: 'the exact parent retry must enter the OCC provider once',
                timeout: 10000,
            },
        ).toBe(failed.service.requestsStarted + 1);
        await expect.poll(
            () => page.evaluate(() => (globalThis as any)
                .__occServiceTestHooks.snapshot().activeGeneration),
            { message: 'the retry must boot a replacement worker generation', timeout: 30000 },
        ).toBe(2);
        await page.waitForFunction(
            () => ((window as any).__occExports?.length ?? 0) === 1,
            null,
            { timeout: 180000 },
        );

        const recovered = await page.evaluate(() => {
            const runtime = globalThis as any;
            return {
                exports: runtime.__occExports,
                service: runtime.__occServiceTestHooks.snapshot(),
                schedulerDead: runtime.__wxScheduler?.dead === true,
                occWaits: runtime.__wxScheduler?.pendingWaits?.('occ') ?? -1,
            };
        });
        expect(recovered.exports).toHaveLength(1);
        expect(recovered.exports[0].magic.startsWith('ISO-10303-21'), 'retry returns real STEP bytes')
            .toBe(true);
        expect(recovered.exports[0].size, 'retry returns a non-trivial STEP file')
            .toBeGreaterThan(10_000);
        expect(recovered.service.activeGeneration, 'retry must own a replacement generation').toBe(2);
        expect(recovered.service.requestsStarted,
            'the parent retry must add exactly one provider entry')
            .toBe(failed.service.requestsStarted + 1);
        expect(recovered.service.requestsPosted,
            'the parent retry must post exactly once to the replacement worker')
            .toBe(failed.service.requestsPosted + 1);
        expect(recovered.service.workerGenerationsStarted,
            'the retry must create exactly one replacement generation')
            .toHaveLength(failed.service.workerGenerationsStarted.length + 1);
        expect(recovered.service.workerGenerationsStarted,
            'the replacement generation must be the active one').toContain(2);
        expect(recovered.service.pending, 'replacement generation must quiesce').toBe(0);
        expect(recovered.schedulerDead, 'the worker failure must not terminalize the editor').toBe(false);
        expect(recovered.occWaits, 'the replacement native OCC wait must quiesce').toBe(0);

        // Dismiss the retry's "Export complete" report dialog via its modal
        // lease (export dialog holds 1; the report raises it to 2).
        await dismissReportDialog(page, 1, 'retry export complete');
    });
});