ark-chainsaw-testing

Ark Chainsaw テスト

Ark リソースの Chainsaw E2E テストを実行、作成します。

テストの実行

# Run all standard tests
(cd tests && chainsaw test --selector 'standard')

# Run specific test
chainsaw test ./tests/query-parameter-ref --fail-fast

# Debug mode - keep resources on failure
chainsaw test ./tests/query-parameter-ref --skip-delete --pause-on-failure

テストの作成

包括的なパターンについては、tests/CLAUDE.md を参照してください。

テスト作成に適したパターンを示す、完全に動作する例については、examples.md を参照してください。

テスト構成

tests/my-test/
├── chainsaw-test.yaml      # Test definition
├── mock-llm-values.yaml    # Mock LLM config (if needed)
├── README.md               # Required documentation
└── manifests/
    ├── a03-model.yaml      # Model before Agent
    ├── a04-agent.yaml      # Agent before Query
    └── a05-query.yaml      # Query last

アンチパターン

CRD の条件確認に kubectl wait を使う

CRD の準備状態を確認するために、決して kubectl wait --for=condition=Established を使わないでください。.status.conditions が nil の場合、このコマンドは型エラーでクラッシュします（既知の kubectl のバグ：kubernetes/kubernetes#66439）。

error: .status.conditions accessor error: <nil> is of the type <nil>, expected []interface{}

代わりに、JMESPath を使った Chainsaw の assert を使用してください。これは適切にポーリングし、フィールドが現れるまで待機します。

# Bad - crashes if .status.conditions is nil
- script:
    content: |
      kubectl apply -f my-crd.yaml
      kubectl wait --for=condition=Established crd/my-crd.example.com --timeout=60s

# Good - polls until condition appears, no nil crash
- script:
    content: |
      kubectl apply -f my-crd.yaml
- assert:
    resource:
      apiVersion: apiextensions.k8s.io/v1
      kind: CustomResourceDefinition
      metadata:
        name: my-crd.example.com
      status:
        (conditions[?type == 'Established']):
          - status: "True"

このパターンを使うと、脆弱なタイムアウトを明示的な条件確認に置き換えられます。同じことは、.status.conditions が最初は nil の可能性があるすべてのリソースに当てはまります。

Query の完了待ちに assert ではなく wait を使う

Query の完了を待つために、決して assert を使わないでください。assert は API サーバーを繰り返しポーリングしますが、wait は Kubernetes のウォッチ（イベント駆動型）を使うため、より高速で低コストです。

# Bad - polls every few seconds, hammers the API server
- assert:
    resource:
      apiVersion: ark.mckinsey.com/v1alpha1
      kind: Query
      metadata:
        name: test-query
      status:
        phase: done

# Good - uses a watch, fires once the condition is set
- wait:
    apiVersion: ark.mckinsey.com/v1alpha1
    kind: Query
    name: test-query
    timeout: 4m
    for:
      condition:
        name: Completed
        value: 'True'

wait で Query の完了を確認した後にのみ、応答フィールドの完了後検証などに assert を使ってください。タイミングを明確にするため、これらは別々のステップにしてください。

- name: wait-for-query-completion
  try:
  - wait:
      apiVersion: ark.mckinsey.com/v1alpha1
      kind: Query
      name: test-query
      timeout: 4m
      for:
        condition:
          name: Completed
          value: 'True'

- name: validate-response
  try:
  - assert:
      resource:
        apiVersion: ark.mckinsey.com/v1alpha1
        kind: Query
        metadata:
          name: test-query
        status:
          (response != null): true
          phase: done

条件確認にシェルスクリプトを使う

Chainsaw のアサーションで宣言的に確認できるリソース状態を検証するために、kubectl get と jq を使ったシェルスクリプトを使うのは避けてください。シェルスクリプトは予期しない nil 値に直面するとすぐに失敗しますが、アサーションは条件が満たされるか、タイムアウトが経過するまで再試行します。

# Bad - fails immediately if field is absent
- script:
    content: |
      val=$(kubectl get myresource foo -o jsonpath='{.status.phase}')
      [ "$val" = "Ready" ] || exit 1

# Good - retries until condition is true
- assert:
    resource:
      apiVersion: example.com/v1
      kind: MyResource
      metadata:
        name: foo
      status:
        phase: Ready

環境変数

実際の LLM テスト（mock-llm ではないテスト）の場合：

export E2E_TEST_AZURE_OPENAI_KEY="your-key"
export E2E_TEST_AZURE_OPENAI_BASE_URL="your-endpoint"