byte-code-pytest

English | 简体中文

pytest ↔ ByteCode 平台桥：测试跑完，整批结果自动上报平台执行记录（test_runs），用例与代码三层映射。纯标准库实现，CI 安装即用、零第三方依赖。

相关仓库

三仓分工：pytest（本插件）与任意 junit 生态（经 CLI）执行测试 → 平台落执行记录 → 失败一键转缺陷任务 → agent 经 CLI 认领修复 → 重跑验证闭环。

目录

• 相关仓库
• 功能特性
• 快速开始
• 用例映射（三层）
• 状态映射
• 配置
• CI 示例（GitHub Actions）
• 权限说明
• 开发
• 发版
• 开源许可证

功能特性

• 一键批量上报 — session 结束整批上报执行记录，逐用例状态、耗时与失败 traceback 直达平台 Web
• 三层用例映射 — 显式 marker / 按 nodeid 自动同步 / 仅记录 external_key，历史可追溯、随时再映射
• 零依赖零开销 — 纯 Python 标准库；不加 --bcode 完全不介入测试流程
• 离线补传 — --bcode-dump 结果落盘 JSON，联网后 bcode test --upload 补传
• CI 友好 — 上报失败默认仅告警不影响测试结论（--bcode-strict 可硬卡）；凭据走环境变量/CI secret 不入库

快速开始

pip install byte-code-pytest

# 平台侧：owner 在项目里接入一个 agent（拿 bc_ key），勾选「上报测试执行」能力
pytest --bcode \
  --bcode-url https://bc.example.com/api \
  --bcode-key "$BCODE_KEY" \
  --bcode-project 42

session 结束自动批量上报，控制台输出：

[bcode] 已上报执行记录 run #77（5 用例，项目 42）

平台 Web「项目 → 测试 → 执行记录」即可看逐用例状态、耗时与失败 traceback。

用例映射（三层）

pytest 用例与平台测试用例的对应关系，按优先级：

1. 显式映射：@pytest.mark.bytecode(case=123) → 直接关联平台用例 #123
2. 自动同步（--bcode-sync）：按 external_key（pytest nodeid）查平台用例，不存在则以 nodeid 为标题自动创建；幂等，重跑不重复建
3. 仅记录（默认）：test_case_id=0，nodeid 照记入 external_key——历史可追溯，随时可再映射

import pytest

@pytest.mark.bytecode(case=123)   # 显式关联平台用例 #123
def test_checkout():
    assert checkout() == "ok"

状态映射

失败与错误的 traceback 附加在用例 message 上（客户端截断 4000 字符，服务端兜底 8000）。teardown 失败不改变用例结论，仅追加提示。

配置

分支与 commit 缺省从 git 自动探测；非 git 环境留空不影响上报。

离线/受限网络场景：pytest --bcode --bcode-dump run.json 把结果落盘（格式带 bcode-test-run 标记壳），之后在能联网的机器 bcode test --upload run.json 补传。

CI 示例（GitHub Actions）

- run: pip install byte-code-pytest
- run: pytest --bcode --bcode-source ci --bcode-env ci
  env:
    BCODE_URL: ${{ vars.BCODE_URL }}
    BCODE_KEY: ${{ secrets.BCODE_KEY }}
    BCODE_PROJECT: ${{ vars.BCODE_PROJECT }}

权限说明

上报走 agent 身份（bc_ key + Bearer），需要项目 owner 给该 agent 勾选上报测试执行（test_execute）能力；CI 机器即 agent，复用平台的租约/审计/能力集。未勾选时上报会被明确拒绝（文案含能力名），配合 --bcode-strict 可在 CI 硬卡。

开发

python -m venv .venv && .venv/Scripts/pip install -e .[dev]
.venv/Scripts/python -m pytest tests/ -q        # pytester 嵌套跑 + 桩平台服务器
.venv/Scripts/python -m ruff check src tests

发版

一键发版（对齐 byte-code 的触发链）：

gh workflow run "Tag Release" -f version=   # 留空=git-cliff 按提交语义自动推导；也可填 patch/minor/major 或完整版本号

Tag Release 自动完成：推导版本 → 重新生成 CHANGELOG 并 bump __version__（版本唯一来源，pyproject 动态读取）→ 提交并打 tag vX.Y.Z → 显式 dispatch Build & Release（GITHUB_TOKEN 推的 tag 不会触发 tag 工作流，GitHub 防递归）：校验 tag 与包版本一致 → build + twine check → PyPI trusted publishing + GitHub Release（cliff 生成发版说明）。

PyPI 侧一次性配置：项目设置里添加 Trusted Publisher（本仓库 + release.yml 工作流 + pypi 环境），之后发版无需任何 token。

开源许可证

MIT © 2026 cicbyte