コンテンツにスキップ

検証

検証は変更の risk に合わせます。本文だけの変更は、実行可能セル、helper crate、browser-visible runtime behavior の変更より軽い check で十分です。

code または config を変更した場合は、必須の lint と format gate を実行します。

ターミナルウィンドウ
pnpm lint
pnpm format:check

pnpm lint は JavaScript、MJS、TypeScript、TSX、Astro に ESLint を warning なしで実行し、Prettier format と Rust formatting check and strict Clippy lint も確認します。設定済みの source、config、Markdown/MDX、JSON、YAML format を適用するには pnpm format を使います。

通常のドキュメント変更では pnpm check を実行します。

ターミナルウィンドウ
pnpm check

この command は development runtime を再生成し、Astro check を実行します。多くの MDX、frontmatter、route、import、TypeScript の問題を検出できます。

prose、navigation、package export、command example、public schema を変更した場合は documentation contract checker も実行します。

ターミナルウィンドウ
pnpm test:docs
pnpm test:package

test:docs は internal file/route/fragment、英日 route parity、sidebar entry、全 package export/path/CLI contract、JSON example、package import、shell command を検証します。test:package は README と必須 public file が npm archive に入ることを確認します。

広い変更が完了したら、可能な範囲で full suite を実行します。

ターミナルウィンドウ
pnpm test

実行可能セル、cell metadata、rich output example、Mermaid example、media example、browser-visible behavior を変更した場合は、次の command を使います。

ターミナルウィンドウ
pnpm wasm:dev
pnpm test:wasm
pnpm test:haskell
pnpm build
pnpm test:bundle
pnpm test:dev-hmr
pnpm test:e2e

pnpm wasm:dev は local development 用 runtime を再生成します。Haskell セルがある場合は wasm32-wasi-ghc が必要で、pnpm build、pnpm check、pnpm wasm:build、pnpm test:wasm でも同じです。pnpm dev と pnpm dev:runtime は意図的により寛容で、Haskell compiler がない、または Haskell compile に失敗しても Astro の serving を続け、browser 上の Haskell セルに error を表示します。pnpm test:wasm は生成 Rust cell の動作を確認し、pnpm test:haskell は生成 Haskell/WASI runtime を実行します。pnpm test:e2e は Chromium、Firefox、WebKit で full browser suite を実行します。

pnpm test:dev-hmr はワークスペースの一時コピーで Chromium の開発スモークテストを実行します。pnpm store からのオフラインインストール、パッケージのビルド、初回 runtime 生成の後に MDX セルを編集し、ソースと reactive 出力の更新が安定することを確認します。先に pnpm install --frozen-lockfile で store を準備してください。Rust/Wasm、wasm32-wasi-ghc、Playwright Chromium が必要です。PR CI では Linux の consumer job で packed consumer smoke の後に1回実行します。

production build は dist/oxiquill/bundle-report.json を生成し、出力された client または worker の JavaScript chunk が uncompressed で 650 KiB を超えると失敗します。pnpm build の後に pnpm test:bundle を実行すると、budget と ECharts/Mermaid の dynamic import boundary を検証できます。

手書き TypeScript、Preact、Node runtime code には unit test を使います。

ターミナルウィンドウ
pnpm test:unit
pnpm test:unit:coverage

coverage は手書きの CLI、Astro integration、config/path、manifest、worker、generator、runtime module に statement/branch/function/line 85% を要求します。除外するのは生成物と type-only declaration だけです。生成物を編集するのではなく、未 covered の手書き code に focused test を追加します。

workspace link を使わない install を、両方の supported package manager で確認します。

ターミナルウィンドウ
pnpm test:consumer:npm
pnpm test:consumer:pnpm
pnpm test:packed-browser

consumer command は oxiquill を pack し、tarball を一時的な standalone project に install して、PATH に Node だけがある状態で zero-cell site を check/build します。その後 Rust/Python cell を追加し、workspace link なしで対応 runtime の生成を検証します。test:packed-browser は install 済み package から Python/Haskell cell も build し、Astro preview を background mode で起動して、実際の worker 経由で両 cell を Chromium 内で実行します。さらに clean が download cache を保持し、offline generation が再利用できることも確認します。

pull request では Linux、macOS、Windows の compatibility job、Linux/macOS の Haskell runtime job、Linux の packed Chromium job、Chromium、Firefox、WebKit の full browser job が必須です。supported matrix の全 cell が merge-blocking です。

必須の Rust minimum job は Rust 1.85.0 で全 generated Rust cell と npm/pnpm packed consumer を検証し、ci-ok に含めます。別の非必須 canary は最新 stable Rust で同じ検証を行い、関連 PR、毎週月曜 03:00 UTC、手動実行で動作します。packed helper fixture は bundled lock にない registry dependency も使用し、tests/runtime/rust-helper-lock-smoke.mjs は dev 専用の package と runtime pin とは別 version の crate を lock に含む helper workspace を build します。

Oxiquill site の再利用可能な任意の Rust helper crate は crates/* にあります。次の command で検証します。

ターミナルウィンドウ
pnpm test:rust
pnpm test:rust:coverage
pnpm lint:rust
pnpm doc:rust

test:rust:coverage は cargo-llvm-cov を使い、helper crate に line/function/region 85% coverage を要求します。helper crate がない場合、helper command は正常に skip します。

  • Unknown Rust crate: cell の crates 値を crates/*/Cargo.toml の package.name に合わせます。
  • Unsupported Python package: vendored Pyodide package を使うか、docs に書く前に package support を追加します。
  • Missing Python runtime: public/oxiquill/pyodide があるか確認し、pnpm wasm:dev または pnpm build を実行します。
  • Missing Haskell compiler: wasm32-wasi-ghc を install し、ghc-wasm-meta を使っている場合は ~/.ghc-wasm/env を source するか、OXIQUILL_HASKELL_GHC に compiler path を指定してから pnpm wasm:dev または pnpm build を実行します。
  • Missing Haskell runtime: public/oxiquill/haskell-wasm/status.json があるか確認し、runtime generation を再実行します。
  • Mermaid failure: code block language が mermaid か確認し、pnpm build で MDX error を確認します。
  • Missing media: file が public/media 配下にあり、MDX URL が /media/ で始まるか確認します。
  • Coverage failure: 生成物ではなく手書き source に focused test を追加します。
  • Documentation link/contract failure: exception を追加せず、referenced page、route、public contract table、canonical command を修正します。

通常の CI は変更分類、JavaScript 品質、Rust 品質、サイトビルド、3ブラウザ、Linux runtime、3 OS の consumer、最終集約の ci-ok の12ジョブです。Markdown のみの変更では変更分類、JavaScript 品質、Rust 品質、ci-ok の4ジョブになります。それ以外は Linux のサイト・runtime・consumer を実行し、package source、package test、root package metadata、lockfile、GitHub 設定の変更では macOS/Windows の consumer も実行します。MDX は実行可能なサイト内容として扱います。release/ で始まるブランチは全件を実行します。

ブラウザはサイトビルドだけを待ちます。Chromium で bundle report を検査し、チャート関連・style・ECharts 依存が変わった場合だけ変更前の画面を撮影します。Linux は npm、ブラウザ付き pnpm、HMR、macOS は pnpm と unit、Windows は npm と unit を検証します。Rust lint は cargo fmt --check も含みます。最終集約は意図的なスキップを許容し、失敗・キャンセルを失敗にします。

Rust セル先頭の YAML コメントに tests を指定します。各項目は default または cases の id と、空でない expect リストを持ちます。同じケースは一度だけ指定できます。テストメタデータは表示されず、読者用マニフェストにも含まれません。

Rust + Wasm

tested-square

Cell actions
Cell inputs
if n == 0 { return Err("n must be positive".to_owned()); }
emit_json!(&(n * n));

Run the cell to show its output.

各期待値には次の形式を一つだけ指定します。

形式成功条件
{ error: "substring" }実行エラーが 1–256 UTF-8 バイトの指定文字列を含むこと。このテスト内で唯一の期待値にします。
{ path: "/outputs/0/value", equals: 4 }型変換なしで JSON の構造と値が等しいこと。
{ path: "/outputs/0/value", range: { min: 1, max: 10 } }有限数が境界を含む範囲内であること。上下限の少なくとも一方が必要です。
{ path: "/outputs/0/value", approx: { value: 0, atol: 1.0e-8 } }abs(actual - value) <= atol + rtol * abs(value)。許容誤差の既定値はゼロで、有限かつ非負、少なくとも一方は正である必要があります。

path は正規化後の { "outputs": [...] } に対する RFC 6901 JSON Pointer です。空文字列はルート、~0 は ~、~1 は / を表します。artifact: <id> を追加すると、その安定 id を持つ artifact を起点にします。例は { artifact: plot, path: /spec/kind, equals: line } です。Rust のグラフ、シーン、表はこの id を metadata = ... から受け取るため、emit_table_with_columns!(columns, rows, metadata = json!({ "id": "scores" })) は、出力内の位置にかかわらず { artifact: scores, path: /rows/0/1, equals: 3 } で検査できます。パスや artifact がなければ失敗します。文字列と null を数値に変換しません。

ハーネスはブラウザーと同じ出力制限と artifact 検証を適用し、宣言された条件だけを判定します。iteration-limit などのステータス値や artifact 検証診断は実行エラーではありません。実行ごとに新しい Wasm インスタンスを使い、セルの timeoutMs を適用します。タイムアウトは、エラーを期待するテストでも失敗します。

ターミナルウィンドウ
pnpm exec oxiquill test-wasm
pnpm exec oxiquill test-wasm --page ja/guides/validation.mdx --cell tested-square --case larger
pnpm exec oxiquill test-wasm --all-cases --format json

セレクターがなければ全 Rust セルの既定入力と全宣言テストを実行します。default の宣言テストがあれば、その既定入力実行の判定条件になります。--all-cases はテスト未指定の名前付きケースもスモーク検証します。--case は実行可能なケースを絞るだけなので、未指定ケースには --all-cases が必要です。Python と Haskell の宣言テストは未対応です。フィルターなしでは従来の Haskell スモーク検証も実行しますが、page、cell、case の指定時は省略します。

失敗にはページ、フェンス行、セル、ケース、期待値の位置、条件、長さ制限付き実際値を表示します。セレクターと NDJSON の詳細は CLI を参照してください。

生成された HTML を検証して、存在しないルート、変更された見出し、生成セルや安定参照のアンカーへのリンク切れを検出します。

ターミナルウィンドウ
pnpm exec oxiquill build --check-links
pnpm exec oxiquill check-links --format json

単独コマンドは直近のビルドを利用し、ファイルに書き込みません。ローカルリダイレクトをたどり、アセットの存在を確認します。外部ホストへの通信は行いません。失敗時は解決先、理由、参照元ページの例を表示します。リンクのソースを修正するか対象を復元し、再ビルドして検証してください。

利用側サイトの CI では、依存関係とセルに必要なツールチェーンを準備した後に、ビルドと検証をまとめて実行できます。

- name: Build and validate local links
run: pnpm exec oxiquill build --check-links

リンク切れがあると非ゼロで終了しますが、調査用のビルド出力は保持します。base の扱い、失敗理由、NDJSON 形式は CLI のリンク検証 を参照してください。