Files
clean-architecture-frontend…/tests/unit/optional-runtime-host.test.ts
DongHyeonka 48a4074e3a fix(bootstrap): 시작할 런타임이 없는 선택 capability를 조립 때 거절한다 (09-07)
문제: 선택 파일은 "Adding an entry here is what installs a capability"라고
적지만 optional host가 실제로 시작하는 것은 Service Worker뿐이다.
realtime·webWorkers·offlineCommands에 항목을 넣으면 아무것도 시작되지
않고 health는 UNAVAILABLE로 남는데, 플랫폼 개요가 읽는 스냅샷은 그
선택을 active로 세어 "활성 (1)"을 보인다. 경고도 실패도 없다.

고른 방법:
- `createOptionalRuntimeHost`가 시작 수단이 없는 capability(realtime,
  webWorkers, offlineCommands)가 선택돼 있으면 그 이름을 모두 담아
  throw한다. 런타임 설정으로 끈 선택은 resolve 단계에서 빠지므로 막지
  않는다. host는 부트 조립에서 만들어지므로 부트 실패 화면으로 드러난다.
- 선택 파일 주석을 "Service Worker만 여기서 설치된다. 나머지는
  composition에 런타임을 먼저 연결해야 한다"로 고쳤다.

버린 대안: 주석만 고치기. 스냅샷이 계속 active로 세고, 선택한 제품은
여전히 아무 신호도 받지 못한다.

위험·한계:
- 런타임을 연결하는 제품은 host의 시작 순서와 이 검사를 함께 바꿔야
  한다(09-02 확장 지점과 같은 자리). 검사 주석에 적었다.
- health 계산의 세 capability `UNAVAILABLE` 분기는 이제 닿지 않지만,
  런타임을 연결할 때 쓸 자리라 남겼다.
- 리뷰 09-05(선택 파일에서 템플릿 상태 설명 분리)는 하지 않았다.
- 초기 JS +127 B gzip(202,995 → 203,122 B, 여유 1,678 B).

검증:
- RED: tests/unit/optional-runtime-host.test.ts의 새 테스트 3건(capability별
  하나)이 "expected [Function] to throw an error"로 실패.
- GREEN: 같은 파일 9건 통과.
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,933건, tests/integration
  (프로세스를 띄우는 3개 제외) 131건, tests/{component,platform,
  architecture,features,contract} 570건 통과. 그중
  app-build-input.test.ts 1건이 부하 25에서 10초 시간 초과로 실패했고,
  heavy lock 아래 단독 재실행에서 4건 통과. tsc app·test 통과. 바꾼 파일
  eslint 통과.
2026-11-01 22:56:29 +09:00

177 lines
5.6 KiB
TypeScript

import { describe, expect, it, vi } from "vitest";
import { createOptionalRuntimeHost } from "../../src/bootstrap/optional-runtime-host.ts";
import type { ResolvedRuntimeCapabilities } from "../../src/contracts/runtime-capabilities.ts";
import type {
ServiceWorkerRuntimeHost,
ServiceWorkerStartOutcome,
} from "../../src/contracts/service-worker.ts";
const capabilities: ResolvedRuntimeCapabilities = Object.freeze({
realtime: Object.freeze([]),
webWorkers: Object.freeze([]),
serviceWorker: null,
serviceWorkerDisabledCleanup: false,
offlineCommands: null,
});
function deferred<Value>() {
let resolve!: (value: Value) => void;
const promise = new Promise<Value>((settle) => {
resolve = settle;
});
return { promise, resolve } as const;
}
describe("optional runtime host", () => {
it("keeps stop-before-start terminal without acquiring browser resources", async () => {
const serviceWorker: ServiceWorkerRuntimeHost = {
start: vi.fn(
async (): Promise<ServiceWorkerStartOutcome> => ({
kind: "ACTIVE",
buildId: "build-1",
}),
),
requestActivation: vi.fn(),
resetOwnedCaches: vi.fn(),
stop: vi.fn(async () => {}),
};
const addEventListener = vi.fn();
const runtime = createOptionalRuntimeHost({
capabilities,
routerBasePath: "/",
buildId: "build-1",
serviceWorkerHost: serviceWorker,
browserLifecycleHost: {
addEventListener,
removeEventListener: vi.fn(),
},
});
await runtime.stop();
await runtime.startAfterMount();
expect(runtime.browserLifecycle()).toBeNull();
expect(runtime.health().serviceWorker).toBe("DISABLED");
expect(addEventListener).not.toHaveBeenCalled();
expect(serviceWorker.start).not.toHaveBeenCalled();
expect(serviceWorker.stop).not.toHaveBeenCalled();
});
it("serializes stop behind an in-flight start and suppresses late health", async () => {
const start = deferred<ServiceWorkerStartOutcome>();
const serviceWorker: ServiceWorkerRuntimeHost = {
start: vi.fn(() => start.promise),
requestActivation: vi.fn(),
resetOwnedCaches: vi.fn(),
stop: vi.fn(async () => {}),
};
const runtime = createOptionalRuntimeHost({
capabilities,
routerBasePath: "/",
buildId: "build-1",
serviceWorkerHost: serviceWorker,
browserLifecycleHost: {
addEventListener: vi.fn(),
removeEventListener: vi.fn(),
},
});
const starting = runtime.startAfterMount();
const stopping = runtime.stop();
start.resolve({ kind: "ACTIVE", buildId: "build-1" });
await Promise.all([starting, stopping]);
expect(serviceWorker.stop).toHaveBeenCalledTimes(1);
expect(runtime.health().serviceWorker).toBe("DISABLED");
expect(runtime.browserLifecycle()).toBeNull();
});
// 06-05. An ACTIVE selection whose worker install fails must be visible to
// operators, not only in `health()`, which nothing reads.
it.each([
{
outcome: { kind: "FAILED", code: "INSTALL_FAILED" } as const,
events: [
[
"service-worker.start.failed",
{ error_kind: "INSTALL_FAILED", build_id: "build-1" },
],
],
},
{
outcome: { kind: "INCOMPATIBLE" } as const,
events: [
[
"service-worker.start.failed",
{ error_kind: "INCOMPATIBLE", build_id: "build-1" },
],
],
},
{ outcome: { kind: "ACTIVE", buildId: "build-1" } as const, events: [] },
{ outcome: { kind: "RELOAD_TO_ENABLE" } as const, events: [] },
])(
"records $outcome.kind as $events.length telemetry event(s)",
async ({ outcome, events }) => {
const emit = vi.fn();
const runtime = createOptionalRuntimeHost({
capabilities: {
...capabilities,
serviceWorker: {
mode: "ACTIVE",
scriptPath: "service-worker.js",
handlers: ["PWA_STATIC_ASSETS"],
},
},
routerBasePath: "/",
buildId: "build-1",
serviceWorkerHost: {
start: vi.fn(async (): Promise<ServiceWorkerStartOutcome> => outcome),
requestActivation: vi.fn(),
resetOwnedCaches: vi.fn(),
stop: vi.fn(async () => {}),
},
browserLifecycleHost: {
addEventListener: vi.fn(),
removeEventListener: vi.fn(),
},
telemetry: { emit },
});
await runtime.startAfterMount();
expect(emit.mock.calls).toEqual(events);
await runtime.stop();
},
);
// 09-07. Only the Service Worker has a runtime this host starts. A selection
// nothing starts used to boot quietly while the platform overview counted
// it as active. The host only reads whether something is selected, so the
// selections below are placeholders, not valid contributions.
it.each([
{
capability: "realtime",
selected: { realtime: Object.freeze([{}]) as unknown as ResolvedRuntimeCapabilities["realtime"] },
},
{
capability: "webWorkers",
selected: { webWorkers: Object.freeze([{}]) as unknown as ResolvedRuntimeCapabilities["webWorkers"] },
},
{
capability: "offlineCommands",
selected: { offlineCommands: {} as unknown as ResolvedRuntimeCapabilities["offlineCommands"] },
},
])("refuses a selected $capability it has no runtime to start", ({ capability, selected }) => {
expect(() =>
createOptionalRuntimeHost({
capabilities: { ...capabilities, ...selected },
routerBasePath: "/",
buildId: "build-1",
serviceWorkerHost: null,
}),
).toThrow(new RegExp(`no runtime to start them: ${capability}\\.`));
});
});