《移动游戏产品的架构·客户端与移动运行时》1.3 mga-lab 的分层骨架与验收口径

// file: src/lab/skeleton.ts
// tier: L2
// verify: node --test test/core/skeleton.test.ts

import type { Clock } from "../core/clock.ts";
import { EventBus } from "../core/events.ts";
import { fail, type Result } from "../core/result.ts";

export type Tier = "L1" | "L2";

export interface LabHost {
  readonly platform: "android" | "ios";
  readonly locale: string;
  readonly safeAreaTopPx: number;
}

export interface LabEvents {
  "check:start": { readonly id: string };
  "check:end": { readonly id: string; readonly pass: boolean };
}

export interface LabContext {
  readonly clock: Clock;
  readonly host: LabHost;
  readonly bus: EventBus<LabEvents>;
}

export interface LabCase {
  readonly id: string;
  readonly tier: Tier;
  readonly summary: string;
  readonly run: (context: LabContext) => Result<string, string>;
}

export interface ModeledItem {
  readonly id: string;
  readonly assumption: string;
  readonly verifyIn: string;
}

export interface LabFailure {
  readonly id: string;
  readonly reason: string;
}

export interface LabReport {
  readonly tier: Tier;
  readonly total: number;
  readonly passed: number;
  readonly failed: number;
  readonly failures: readonly LabFailure[];
  readonly elapsedMs: number;
}

export const MOCK_HOST: LabHost = {
  platform: "android",
  locale: "zh-CN",
  safeAreaTopPx: 88,
};

export class LabRunner {
  #clock: Clock;
  #host: LabHost;
  #bus: EventBus<LabEvents>;
  #cases = new Map<string, LabCase>();
  #modeled = new Map<string, ModeledItem>();

  constructor(clock: Clock, host: LabHost = MOCK_HOST, bus = new EventBus<LabEvents>()) {
    this.#clock = clock;
    this.#host = host;
    this.#bus = bus;
  }

  get bus(): EventBus<LabEvents> {
    return this.#bus;
  }

  register(testCase: LabCase): void {
    if (this.#cases.has(testCase.id)) {
      throw new Error(`duplicate lab case: ${testCase.id}`);
    }
    this.#cases.set(testCase.id, testCase);
  }

  registerModeled(item: ModeledItem): void {
    if (this.#modeled.has(item.id)) {
      throw new Error(`duplicate modeled item: ${item.id}`);
    }
    this.#modeled.set(item.id, item);
  }

  modeledItems(): readonly ModeledItem[] {
    return [...this.#modeled.values()];
  }

  run(tier: Tier): LabReport {
    const startedMs = this.#clock.nowMs();
    const failures: LabFailure[] = [];
    let passed = 0;
    const context: LabContext = {
      clock: this.#clock,
      host: this.#host,
      bus: this.#bus,
    };

    for (const testCase of this.#cases.values()) {
      if (testCase.tier !== tier) {
        continue;
      }
      this.#bus.emit("check:start", { id: testCase.id });
      let outcome: Result<string, string>;
      try {
        outcome = testCase.run(context);
      } catch (error) {
        outcome = fail("exception", `${testCase.id}: ${String(error)}`);
      }
      if (outcome.ok) {
        passed += 1;
      } else {
        failures.push({ id: testCase.id, reason: outcome.reason });
      }
      this.#bus.emit("check:end", { id: testCase.id, pass: outcome.ok });
    }

    return {
      tier,
      total: passed + failures.length,
      passed,
      failed: failures.length,
      failures,
      elapsedMs: this.#clock.nowMs() - startedMs,
    };
  }
}

// file: test/core/skeleton.test.ts
// tier: L2
// verify: node --test test/core/skeleton.test.ts

import { test } from "node:test";
import assert from "node:assert/strict";

import { ManualClock } from "../../src/core/clock.ts";
import { fail, ok } from "../../src/core/result.ts";
import { LabRunner } from "../../src/lab/skeleton.ts";

test("runner separates L1, L2 and modeled items", () => {
  const clock = new ManualClock(1_000);
  const runner = new LabRunner(clock);
  const finished: boolean[] = [];
  runner.bus.on("check:end", (event) => finished.push(event.pass));

  runner.register({
    id: "layers",
    tier: "L1",
    summary: "dependency direction",
    run: () => ok("downward only"),
  });
  runner.register({
    id: "broken",
    tier: "L1",
    summary: "intentional failure",
    run: () => fail("assertion", "expected 3 layers, found 4"),
  });
  runner.register({
    id: "boot",
    tier: "L2",
    summary: "in-process boot with mock host",
    run: (context) => {
      clock.advance(25);
      return ok(`${context.host.platform}:${context.host.locale}`);
    },
  });
  runner.registerModeled({
    id: "thermal",
    assumption: "device temperature rises under sustained 60fps load",
    verifyIn: "chapter 9.3",
  });

  const l1 = runner.run("L1");
  assert.equal(l1.total, 2);
  assert.equal(l1.passed, 1);
  assert.equal(l1.failed, 1);
  assert.deepEqual(l1.failures, [{ id: "broken", reason: "expected 3 layers, found 4" }]);

  const l2 = runner.run("L2");
  assert.equal(l2.total, 1);
  assert.equal(l2.passed, 1);
  assert.equal(l2.elapsedMs, 25);

  assert.deepEqual(finished, [true, false, true]);
  assert.equal(runner.modeledItems().length, 1);
  assert.equal(runner.modeledItems()[0]?.verifyIn, "chapter 9.3");
});

test("runner turns thrown errors into failures", () => {
  const runner = new LabRunner(new ManualClock());
  runner.register({
    id: "boom",
    tier: "L1",
    summary: "throws",
    run: () => {
      throw new Error("host missing");
    },
  });
  const report = runner.run("L1");
  assert.equal(report.failed, 1);
  assert.equal(report.failures[0]?.reason, "boom: Error: host missing");
});

test("duplicate case ids are rejected", () => {
  const runner = new LabRunner(new ManualClock());
  const item = { id: "same", tier: "L1" as const, summary: "x", run: () => ok("x") };
  runner.register(item);
  assert.throws(() => runner.register(item), /duplicate lab case/);
});