レベル3: ビルド出力検証

ビルドされたファイル、SSG出力、テンプレート、バンドラ設定のテスト。

レベル3がテストするもの

レベル3のテストはビルド出力を検証します。ソースコードを直接テストする代わりに、ビルドを実行してその結果を検査します。

典型的な対象：

• SSG（静的サイト生成）出力HTML

• テンプレートのレンダリング結果

• バンドラ出力（正しいチャンク、コード分割）

• 生成された設定ファイル

• ビルド時のデータ変換（MDXコンパイル、コンテンツコレクション）

ツール

ビルドを先に実行する

レベル3のテストはdist/配下のファイルを読み取るだけで、自らビルドをトリガーすることはありません。スイートを実行する前にビルドを実行してください。そうしないと、テストは古い（あるいは存在しない）出力を読むことになります：

pnpm build && pnpm vitest run --project build

--project buildは、Vitestの設定で名前付きのbuildプロジェクトを定義していれば、それにスコープした実行になります（Vitestパターンを参照）。名前付きプロジェクトがない場合は、ビルド後に素のvitest runを実行しても同じように機能します。

開発者がビルドステップを覚えていることに頼らないようにするには、globalSetupでVitest自体に組み込み、素のvitest runが常に最新のビルドに対して実行されるようにします：

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globalSetup: ["./tests/build-setup.ts"],
  },
});

// tests/build-setup.ts
import { execSync } from "node:child_process";

export default function setup() {
  execSync("pnpm build", { stdio: "inherit" });
}

書き手が複数いるビルド成果物は共有された可変状態

上のWarningは書き手が1つだけであることを前提にしています。ビルドして、それから読む、という前提です。単独でpnpm build && vitest runを回している限りこれは成り立ちますが、スイートが読んでいる最中にdist/へ書き込めるものが他にあった瞬間、成り立たなくなります。見落とされる書き手はパッケージのライフサイクルフックです。誰もそれをタイプしないからです -- 読み取り専用に見えるコマンドの副作用として発火します。

ビルド成果物は、共有された可変変数と同じように扱ってください。すなわち、信頼する前にすべての書き手を洗い出すことです。

書き手をすべて洗い出す

「1回ビルドして何度も読む」という構成に頼る前に、その成果物へ書き込みうるプロセスをすべて列挙します：

• ライフサイクルフック -- prepare、prepack、prepublishOnly、postinstall。これらを実行するのは人間ではなく、パッケージマネージャです。

• ウォッチャー -- tsup --watch、tsc --watch。開発サーバーが生きている間ずっと書き込み続けます。

• 強制リビルドするスクリプト -- テストレーン、ワークスペースビルド、ローカルの重量レーンなど、呼ばれるたびに無条件でリビルドするもの。

• publishの経路 -- npm pack、npm publish、およびそれらがあなたの代わりに実行するもの。

実在するpnpmモノレポでは、packages/<pkg>/dist/に独立した書き手が4つ存在していました -- 上のカテゴリからちょうど1つずつです：

これらの重なりを機械的に防ぐ仕組みは何もなく、そのプロジェクトはCLAUDE.mdに書かれた「人間が覚えておくルール」に頼っていました -- pnpm devが動いている間はテストレーンを実行しないこと。これが問題の形です。規律だけが防いでいるレースなのです。その結果、実際に起きたことは：

• --watchビルドがdist/を消し去り、.d.tsを一切再生成しなくなった。cleanをwatchモードのときだけ無効にすること（clean: !options.watch）で修正されました。

• .d.tsのウォッチャーが死んだまま放置され、JSは更新され続けるのにdist/*.d.tsだけが凍結された。その結果スイートは -- そのパッケージ自身の言葉を借りれば -- 大きく失敗する代わりに、古い型に対して静かに型チェックを通してしまいます。ソースともはや一致しない成果物に対するグリーンなスイート。原因はビルドし忘れではなく、並行性です。

• ワークスペースのビルドガードが、自らのドキュメントの記述どおり、フレッシュネスではなく存在だけを確認していた。設計上、古い成果物を受け入れ、鮮度の判断を人間へ差し戻す作りです。

--ignore-scriptsはフラグであってプロパティではない

この抽象を具体的にする実際のインシデントがあります。高速ティアのユニットテストがnpmのtarballに含まれるファイル一覧をアサートしており、その呼び出しを読み取り専用にするためにこそ--ignore-scriptsを渡していました：

execFileSync("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], { cwd: PKG_ROOT });

ところが、このフラグが実際にprepareを抑止するかどうかは、npmのバージョンに依存していました：

ローカル開発はNode 24で動いており、packは本当に読み取り専用でした。一方CIはNode 22をピン留めしていたため、同じコマンドがprepareを発火させ、それがclean: trueのtsupを実行し、dist/をまるごと削除しました。ちょうどそのとき、兄弟のspecがパッケージのbin/*.mjsを起動しており、その静的import（../dist/eject/index.js）がERR_MODULE_NOT_FOUNDで失敗したのです。publishの最中に。リリースは3パッケージのうち1つで停止しました。

はみ出したログ行こそが手がかりだった

このリリース障害の数か月前、CIはすでにビルド自身のログ行 -- [copy-theme-packs] dist/theme-packs/ OK -- がpackのJSONより手前に出力され、JSON.parseを壊すのを目撃していました。この文字列はビルドのonSuccessチェーンからしか出力されません。つまり、読み取り専用のはずのコマンドの内側でライフサイクルがすでに走っていた、という直接の証拠だったのです。そのとき適用された修正は、はみ出した行を読み飛ばす寛容なJSONスキャナでした。症状は隠され、リビルドは走り続け、やがてリリースを落としました。

ルール: 不変のスナップショットを所有する

ビルド成果物を読むテストは、その不変のスナップショットを所有しなければなりません。 そしてビルドのフレッシュネスキーは、ソースだけでなく成果物自身のバイト列をハッシュしなければなりません。

具体的な形は2つあります。

形1 -- 成果物のスナップショットを取る。 npm packしてtarballを展開するか、{bin,dist}をスクラッチディレクトリにコピーし、テストをそのコピーに向けます。そのあとライフサイクルが実際のdist/に何をしようと、テストが読んでいるのは誰も手を触れられないバイト列です。

// tests/setup/snapshot-package.ts
import { cpSync, mkdtempSync } from "node:fs";
import { join } from "node:path";

const PKG_ROOT = join(__dirname, "../..");

export function snapshotPackage(): string {
  // Inside the package root on purpose -- os.tmpdir() breaks bare-specifier
  // resolution. Prefix is gitignored and removed in teardown.
  const dir = mkdtempSync(join(PKG_ROOT, ".artifact-snapshot-"));
  for (const entry of ["bin", "dist", "package.json"]) {
    cpSync(join(PKG_ROOT, entry), join(dir, entry), { recursive: true });
  }
  return dir;
}

形2 -- 入力だけでなく出力もハッシュする。 フレッシュネスマーカーでビルドをキャッシュしているなら、ビルド出力そのものをキーに含めてください。ソースだけから導出したキーは、並行する書き手がマーカーの保証対象である成果物を切り詰めたり、書きかけで放置したり、削除したりしても、依然として一致してしまいます。ソースは変わっていないのですから、マーカーは「もはや記述どおりの状態にないdist/」を平然と受け入れるのです。ここで拡張しているフレッシュネスハッシュのレシピはメカニズム2：変更がなければリビルドをスキップするを参照してください。

このガードが正直に主張できること

機械的なガードは役に立ちます。デフォルトレーンのspecを走査し、ビルドやパッケージライフサイクルのコマンド -- npm|pnpm|yarnに続くpack|publish|install|ci|rebuild|run build、裸のtsupなど -- を起動しているものを見つけ、明示的な注釈のないspecを失敗させる、というものです。

そして同じ場所でその限界も明記してください。文字列スキャナが捕捉できるのは起動されたコマンドだけです。シェルのラッパー、スクリプトのエイリアス、dist/配下への直接のrmSync/writeFileSyncは捕捉できません。したがって、機械的に強制されるルールは、それが守ろうとしている不変条件よりも狭いのであり、ドキュメントはどちらがどちらなのかを述べなければなりません。ガードが強制するのは「specはビルドコマンドを起動しない」であり、不変条件は「specは成果物に書き込まない」です。

例: SSG出力検証

// tests/build-output.test.ts
import { describe, it, expect } from "vitest";
import { readFileSync } from "fs";
import { join } from "path";

const DIST = join(__dirname, "../dist");

describe("build output", () => {
  it("generates index.html with correct title", () => {
    const html = readFileSync(join(DIST, "index.html"), "utf-8");
    expect(html).toContain("<title>My Site</title>");
  });

  it("generates sitemap.xml", () => {
    const sitemap = readFileSync(join(DIST, "sitemap.xml"), "utf-8");
    expect(sitemap).toContain("<urlset");
  });

  it("includes all expected pages", () => {
    const pages = ["index.html", "about/index.html", "docs/index.html"];
    for (const page of pages) {
      const content = readFileSync(join(DIST, page), "utf-8");
      // Case-insensitive: toolchains emit the doctype as lowercase `<!doctype html>`.
      expect(content.toLowerCase()).toContain("<!doctype html>");
    }
  });
});

例: MDXフォーマッターのコントラクトテスト

mdx-formatterの実例パターン：Vitestスイートがフィクスチャファイルで実行して出力を比較することで、Rustフォーマッティングエンジンをテストします。これがレベル1ではなくレベル3である理由は、format()がビルドによって生成されたコンパイル済みのネイティブエンジンを駆動する薄いJSラッパーだからです -- テスト対象はそのビルド成果物であり、手書きのTypeScriptロジックではありません（もしフォーマッターがコンパイル済みバックエンドを持たない純粋なJS/TSであれば、この同じ冪等性チェックはレベル1に属することになります）。

// tests/format.test.ts
import { describe, it, expect } from "vitest";
import { readFileSync } from "fs";
import { join } from "path";
import { format } from "../src/format";

describe("mdx formatting", () => {
  it("is idempotent", () => {
    const input = readFileSync(join(__dirname, "fixtures/sample.mdx"), "utf-8");
    const first = format(input);
    const second = format(first);
    expect(first).toBe(second);
  });
});

出力されたコードを実行する

ここまでの例は、出力を静的なテキストとして比較するものでした。ファイルを読み、その内容に対してアサーションを行います。しかし、ビルドツールの中には実行されるJavaScriptを生成するものがあります。ユーザーのハンドラをラップするアダプタ、バンドラのラッパー、スキャフォルダなどです。これらに対しては、文字列の一致チェックではテンプレートが書き出されたことしか証明できません。生成されたコードが実行時に正しく振る舞うことは証明できないのです。それを検証するには、成果物を書き出し、インポートし、実際に動かす必要があります。

再利用できるレシピは、一時ディレクトリ + 動的インポート + envスタブです。

1. 合成した内側のバンドルをmkdtempで作ったスクラッチディレクトリに書き出す。

2. 出力ステップ（emitWorker()）を実行して、実際の_worker.jsを生成する。

3. 出力されたファイルをimport(pathToFileURL(...))し、default.fetch(new Request(...), envStub)を呼び出す。

4. (env, ctx)が正しく引き渡されていることをアサートする。ビルドが出力するラッパーは、envをユーザーのハンドラへ渡さなければなりません。

5. afterEachでスクラッチディレクトリをクリーンアップする。

// tests/emit-worker.test.ts
import { mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { pathToFileURL } from "node:url";
import { afterEach, describe, expect, it } from "vitest";
import { emitWorker } from "../src/build.js";

let scratchDirs: string[] = [];

afterEach(async () => {
  for (const d of scratchDirs) {
    await rm(d, { recursive: true, force: true });
  }
  scratchDirs = [];
});

async function scratch(): Promise<string> {
  const d = await mkdtemp(join(tmpdir(), "emit-worker-"));
  scratchDirs.push(d);
  return d;
}

describe("emitWorker threads env/ctx into the inner bundle", () => {
  it("the generated wrapper passes env through to the user handler", async () => {
    const dir = await scratch();

    // A synthetic inner bundle that reads env from the request scope
    // the wrapper sets up (here via AsyncLocalStorage), then echoes it.
    const inputPath = join(dir, "inner.mjs");
    await writeFile(
      inputPath,
      `import { AsyncLocalStorage } from "node:async_hooks";
const STORAGE_KEY = "__adapter_als__";
function getStore() {
  const g = globalThis;
  let als = g[STORAGE_KEY];
  if (!als) { als = new AsyncLocalStorage(); g[STORAGE_KEY] = als; }
  return als.getStore();
}
export default {
  async fetch(request) {
    const store = getStore();
    const env = store?.env ?? {};
    return new Response(
      JSON.stringify({
        token: env.API_KEY ?? null,
        ctxKind: typeof store?.ctx?.waitUntil,
      }),
      { status: 200, headers: { "content-type": "application/json" } },
    );
  },
};
`,
      "utf8",
    );

    // Run the real emit step to produce a real _worker.js.
    const out = await emitWorker({
      inputBundlePath: inputPath,
      outdir: join(dir, "dist"),
    });

    // Import the emitted artifact as ESM and drive it with a
    // synthetic Request + env + ctx -- no wrangler / miniflare needed.
    const worker = (await import(pathToFileURL(out.workerPath).href)) as {
      default: {
        fetch: (
          request: Request,
          env: Record<string, unknown>,
          ctx: { waitUntil: (p: Promise<unknown>) => void },
        ) => Promise<Response>;
      };
    };

    const envStub = { API_KEY: "sk-test-1234" };
    const ctx = { waitUntil: () => {} };
    const request = new Request("https://worker.test/api/foo", { method: "POST" });

    const response = await worker.default.fetch(request, envStub, ctx);
    const body = (await response.json()) as { token: string | null; ctxKind: string };

    // The headline check: env actually reached the inner handler.
    expect(body.token).toBe("sk-test-1234");
    // ctx was threaded too -- its surface matches the runtime shape.
    expect(body.ctxKind).toBe("function");
  });
});

ブラインドスポット

レベル3を使用するタイミング