mcpField
A
ark-chainsaw-testing

ark-chainsaw-testing

github.com/mckinsey测试与质量43235 次安装今天更新
代码仓库

关于 ark-chainsaw-testing

帮助 Ark 开发者运行和编写 Chainsaw 端到端测试的技能。它提供测试命令、目录结构示例，以及避免脆弱检查方式的指导。

主要功能

  1. 01运行全部或指定测试
  2. 02提供测试目录结构示例
  3. 03说明 CRD 条件检查方式
  4. 04区分 Query 等待与断言
  5. 05提供真实 LLM 测试环境变量

适用场景

  1. 01运行 Ark 标准端到端测试
  2. 02调试失败的 Chainsaw 测试
  3. 03为 Ark 资源编写测试
  4. 04验证 Query 完成后的响应字段

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mckinsey/agents-at-scale-ark --skill ark-chainsaw-testing

安装后在 Claude Code 中输入/ark-chainsaw-testing确认已加载。

附带文件examples.md

详细介绍

Ark 链锯测试

为 Ark 资源运行并编写 Chainsaw 端到端测试。

运行测试

# 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

反模式

使用 kubectl wait 检查 CRD 条件

切勿使用 kubectl wait --for=condition=Established 检查 CRD 是否就绪。当 .status.conditions 为 nil 时，此命令会因类型错误而崩溃（这是已知的 kubectl bug：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 的资源，同样适用。

使用 assert 而非 wait 等待 Query 完成

切勿使用 assert 等待 Query 完成。assert 会反复轮询 API 服务器；wait 使用 Kubernetes watch（由事件驱动），速度更快且开销更低：

# 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 确认查询已完成后，才使用 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
使用 Shell 脚本检查条件

当 chainsaw 断言能够声明式地表达检查时，避免使用 Shell 脚本结合 kubectl get 和 jq 来验证资源状态。Shell 脚本遇到意外的 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

环境变量

用于真实的大模型测试（非 mock-llm）：

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

评论

支持 Markdown