mcpField
T
test-component

test-component

github.com/keboola测试与质量17189 次安装1 天前更新
代码仓库

关于 test-component

为 Keboola Python 组件提供测试方法与配置指导，面向组件开发者。涵盖数据目录测试、单元测试及外部 HTTP API 的 VCR 功能测试，并提供搭建与排错参考。

主要功能

  1. 01数据目录功能测试
  2. 02单元测试与模拟
  3. 03VCR 录制和回放
  4. 04测试配置与脚手架指导
  5. 05测试故障排查参考

适用场景

  1. 01为组件验证输入、输出和状态
  2. 02测试调用外部 API 的提取器
  3. 03为纯逻辑编写隔离测试

安装

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

$npx skills add https://github.com/keboola/ai-kit --skill test-component

安装后在 Claude Code 中输入/test-component确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
datadir-tests.md
unit-and-mock-tests.md
vcr-configs-format.md
vcr-debug-from-platform.md
vcr-quickstart.md
vcr-sanitizers.md
vcr-troubleshooting.md

详细介绍

Keboola 组件测试器

测试方法

按优先级分为三个层级：

  1. Datadir 测试 — 使用 KBC_DATADIR 结构进行功能测试；这是所有组件的主要测试方法
  2. 单元测试 — 针对转换、验证和配置解析的隔离逻辑测试
  3. VCR 功能测试 — 适用于调用外部 HTTP API 的组件（相比手动模拟，更推荐用于提取器/写入器）

选择 VCR 还是模拟

组件会进行外部 HTTP 调用时，使用 VCR（keboola.datadirtest）：

  • 记录一次真实的 API 交互 → 在 CI 中无凭据地确定性重放
  • 比手动编写的模拟更真实；能捕获 API 契约变更
  • 提取器必须使用；对于调用外部 API 的写入器，建议使用

以下情况使用模拟（unittest.mock）：

  • 测试纯逻辑、转换或验证代码
  • 为单个函数编写单元测试
  • 组件不进行 HTTP 调用（应用程序、纯转换）

VCR 设置工作流

  1. 将 keboola.datadirtest>=2.0.0 添加到 pyproject.toml 的开发依赖项中，然后运行 uv sync -U
  2. 从 component-developer:component-defaults 资源中复制 tests/test_functional.py
  3. 阅读组件文件（src/component.py、src/configuration.py、component_config/configSchema.json），并构建 tests/setup/configs.json — 参见 vcr-configs-format.md
  4. 对于经过身份验证的 API：向用户索取真实凭据 → 保存到 secrets.json（确认该文件已列入 .gitignore）
  5. 搭建脚手架以记录交互：uv run python -m keboola.datadirtest scaffold [--secrets secrets.json] [--chain-state]
  6. 检查录制文件中是否有未经清理的动态值 — 参见 vcr-sanitizers.md
  7. 更新 .gitignore、Dockerfile（COPY tests/ tests）和 push.yml（使用 python -m pytest）
  8. 验证：在本地和 Docker 中运行 python -m pytest

所有脚手架命令请参见 vcr-quickstart.md。常见故障请参见 vcr-troubleshooting.md。

参考资料

文件阅读时机
references/datadir-tests.md设置 datadir 测试 — 目录结构、config.json、输出断言、状态、错误情况
references/unit-and-mock-tests.md单元测试、模拟模式、freezegun，以及按组件类型划分的测试
references/vcr-configs-format.md构建 configs.json — 封装格式、OAuth、写入器、覆盖率指南
references/vcr-sanitizers.md添加 VCR_SANITIZERS — DefaultSanitizer、ResponseUrlSanitizer、QueryParamSanitizer
references/vcr-quickstart.md所有脚手架/录制命令及仓库布局
references/vcr-troubleshooting.md常见 VCR 故障及修复方法
references/vcr-debug-from-platform.md根据 Keboola 平台调试任务输出（stage_output.zip）编写回归测试

评论

支持 Markdown