❄️ 我的个人专栏《智能软件工程AI4SE》《嵌入式面试总结》《嵌入式处理器架构解析》《嵌入式与虚拟化》《嵌入式软件测试》 Simplicity is the ultimate sophistication摘要本文面向嵌入式软件工程师介绍如何把 JUnitJava 侧与 pytestPython 侧接入 GitHub Actions实现「提交即测、失败即拦」的入门配置。文章从 CI 中跑动态测试的价值出发依次给出 JUnit 与 pytest 的最小 workflow 配置、测试报告上传与依赖缓存加速并讲解如何通过分支保护规则让测试失败真正阻断合入最后汇总本地通过但 CI 失败、硬件相关测试、YAML 语法错误等常见问题的排查思路。1. 引言在嵌入式软件研发流程中动态测试往往停留在「本地跑一遍、通过就提交」的阶段。随着团队规模扩大、代码合入频率提升仅靠人工触发测试既容易遗漏也难以在问题扩散前及时拦截。把 JUnit 或 pytest 接入 GitHub Actions让每次提交都自动触发测试、失败即阻断合入是提升嵌入式软件质量门槛的一条低成本路径。本文面向嵌入式软件工程师介绍如何把 JUnitJava 侧与 pytestPython 侧接入 GitHub Actions实现「提交即测、失败即拦」的入门配置。全文以可复制的 YAML 配置和常见问题排查为主不涉及复杂平台搭建。2. 为什么要在 CI 中跑动态测试嵌入式软件通常包含驱动、算法、协议栈与上层应用等多个层次。动态测试的价值在于用真实或仿真环境验证行为是否符合预期。把动态测试接入 CI 后可以获得三方面收益尽早发现问题每次提交都触发测试缺陷在合入前暴露修复成本远低于集成阶段。统一测试基线所有开发者在同一套测试命令与环境下运行避免「本地能过、别人跑不过」的差异。强制质量门槛测试失败即阻断合入让质量要求从口头约定变成可执行的门禁。需要说明的是嵌入式动态测试并不一定都要在真实硬件上执行。对于算法、协议解析、状态机等纯逻辑模块完全可以在主机环境用 JUnit 或 pytest 完成单元级动态测试涉及硬件的部分再通过硬件在环或仿真环境补充。3. 准备工作在编写 GitHub Actions 配置之前需要确认以下前提代码仓库托管在 GitHub或使用支持 GitHub Actions 的托管平台。被测模块可以在主机环境编译并运行或至少核心逻辑部分可以脱离硬件执行。测试框架已在本地产出可重复执行的命令例如mvn test或pytest。仓库根目录存在可用的构建文件如pom.xml、requirements.txt或pyproject.toml。如果当前仓库还没有任何 CI 配置建议先创建一个.github/workflows目录后续的 YAML 文件都放在该目录下。4. JUnit 接入 GitHub ActionsJUnit 通常配合 Maven 或 Gradle 使用。下面以 Maven 项目为例给出一个最小可用的 GitHub Actions 配置。4.1 创建 workflow 文件在仓库中新建.github/workflows/java-test.yml内容如下name: Java Unit Tests on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Set up JDK 17 uses: actions/setup-javav4 with: distribution: temurin java-version: 17 name: Run unit tests run: mvn test这段配置的含义是当代码推送到main或develop分支或向main发起 Pull Request 时自动在 Ubuntu 环境执行mvn test。任何测试失败都会导致任务失败从而阻止合入。4.2 上传测试报告为了让失败原因更直观可以在测试后上传 JUnit 生成的 XML 报告。修改上述配置增加一个上传步骤- name: Upload test report uses: actions/upload-artifactv4 if: always() with: name: junit-report path: target/surefire-reports/这里使用if: always()确保即使测试失败也会上传报告方便在 Actions 页面下载查看。4.3 缓存依赖加速嵌入式 Java 项目依赖较多每次全量下载会拖慢流水线。可以加入 Maven 依赖缓存- name: Cache Maven dependencies uses: actions/cachev4 with: path: ~/.m2/repository key: ${{ runner.os }}-maven-${{ hashFiles(**/pom.xml) }} restore-keys: | ${{ runner.os }}-maven-缓存命中后后续运行会明显加快。5. pytest 接入 GitHub ActionsPython 侧的动态测试接入方式与 JUnit 类似核心是配置 Python 环境并执行 pytest。下面给出一个适用于嵌入式 Python 模块的配置。5.1 创建 workflow 文件在仓库中新建.github/workflows/python-test.yml内容如下name: Python Unit Tests on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Set up Python uses: actions/setup-pythonv5 with: python-version: 3.11 name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install pytest name: Run tests run: pytest -v如果项目使用pyproject.toml管理依赖可以把安装步骤改为pip install -e .或pip install .具体取决于项目配置。5.2 指定测试目录嵌入式项目常把测试放在tests目录下与源码分离。此时可以显式指定测试路径- name: Run tests run: pytest tests/ -v如果某些测试依赖硬件或特定环境建议用 pytest 的标记机制跳过而不是让整个流水线失败。例如在测试文件中标记import pytest pytest.mark.hardware def test_uart_send(): ...然后在 CI 中排除该标记- name: Run tests run: pytest tests/ -v -m not hardware这样硬件相关测试留在本地或专门的硬件在环流水线执行主机 CI 只跑纯逻辑测试。6. 失败即拦分支保护配置仅仅在 Actions 中跑测试还不够要让「失败即拦」真正生效还需要在 GitHub 仓库设置分支保护规则。6.1 开启分支保护在仓库页面进入Settings→Branches→Add branch protection rule针对main分支配置勾选Require status checks to pass before merging。在搜索框中选中对应的 workflow 名称例如Java Unit Tests或Python Unit Tests。勾选Require branches to be up to date before merging确保合入前测试基于最新代码。配置完成后任何未通过测试的 Pull Request 都无法合入从机制上实现「失败即拦」。6.2 多测试并行如果仓库同时包含 Java 和 Python 模块可以让两个 workflow 并行执行。GitHub Actions 默认支持多个 workflow 并行无需额外配置。分支保护中可以把两个状态检查都设为必需只有全部通过才允许合入。7. 常见问题与排查接入过程中容易遇到以下几类问题这里给出排查思路。7.1 测试在本地通过、CI 失败最常见的原因是环境差异。排查顺序建议为确认 CI 使用的 JDK 或 Python 版本与本地一致。检查依赖是否完整声明避免依赖本地已安装但未写入配置文件的包。确认测试是否依赖绝对路径或本地环境变量。7.2 硬件相关测试导致 CI 失败如果测试代码直接访问串口、GPIO 或网络设备在 Ubuntu 主机环境必然失败。解决方案是使用 pytest 标记或 JUnit 的Disabled注解把硬件相关用例排除在 CI 之外或单独建立硬件在环流水线。7.3 workflow 文件语法错误YAML 对缩进敏感常见错误包括多一个空格、tab 与空格混用。建议在本地用编辑器校验 YAML 语法或先推送一个空任务验证 workflow 能被正确解析。7.4 测试报告无法下载确认上传步骤使用了if: always()否则测试失败时上传步骤会被跳过。同时检查报告路径是否正确例如 Maven 的target/surefire-reports/或 pytest 的--junitxml输出路径。8. 小结把 JUnit 或 pytest 接入 GitHub Actions本质上是把「本地手动测试」升级为「提交自动测试」。对嵌入式软件而言这一步的价值在于纯逻辑模块的回归测试可以高频、低成本地执行硬件相关问题则通过标记机制分流到专门的测试环境。配合分支保护规则测试失败即阻断合入质量门槛从口头约定变成可执行的门禁。本文给出的配置是入门级的最小方案实际项目中可以根据需要扩展覆盖率统计、静态检查、多平台矩阵等能力。建议先从单个模块试点跑通后再逐步推广到整个仓库。 
长河君 · 2026/10/14 1:50:26 · 阅读 1.2k 嵌入式软件动态测试（三十二）——JUnit / pytest 接入 GitHub Actions：提交即测、失败即拦的入门配置
❄️ 我的个人专栏《智能软件工程AI4SE》《嵌入式面试总结》《嵌入式处理器架构解析》《嵌入式与虚拟化》《嵌入式软件测试》 Simplicity is the ultimate sophistication摘要本文面向嵌入式软件工程师介绍如何把 JUnitJava 侧与 pytestPython 侧接入 GitHub Actions实现「提交即测、失败即拦」的入门配置。文章从 CI 中跑动态测试的价值出发依次给出 JUnit 与 pytest 的最小 workflow 配置、测试报告上传与依赖缓存加速并讲解如何通过分支保护规则让测试失败真正阻断合入最后汇总本地通过但 CI 失败、硬件相关测试、YAML 语法错误等常见问题的排查思路。1. 引言在嵌入式软件研发流程中动态测试往往停留在「本地跑一遍、通过就提交」的阶段。随着团队规模扩大、代码合入频率提升仅靠人工触发测试既容易遗漏也难以在问题扩散前及时拦截。把 JUnit 或 pytest 接入 GitHub Actions让每次提交都自动触发测试、失败即阻断合入是提升嵌入式软件质量门槛的一条低成本路径。本文面向嵌入式软件工程师介绍如何把 JUnitJava 侧与 pytestPython 侧接入 GitHub Actions实现「提交即测、失败即拦」的入门配置。全文以可复制的 YAML 配置和常见问题排查为主不涉及复杂平台搭建。2. 为什么要在 CI 中跑动态测试嵌入式软件通常包含驱动、算法、协议栈与上层应用等多个层次。动态测试的价值在于用真实或仿真环境验证行为是否符合预期。把动态测试接入 CI 后可以获得三方面收益尽早发现问题每次提交都触发测试缺陷在合入前暴露修复成本远低于集成阶段。统一测试基线所有开发者在同一套测试命令与环境下运行避免「本地能过、别人跑不过」的差异。强制质量门槛测试失败即阻断合入让质量要求从口头约定变成可执行的门禁。需要说明的是嵌入式动态测试并不一定都要在真实硬件上执行。对于算法、协议解析、状态机等纯逻辑模块完全可以在主机环境用 JUnit 或 pytest 完成单元级动态测试涉及硬件的部分再通过硬件在环或仿真环境补充。3. 准备工作在编写 GitHub Actions 配置之前需要确认以下前提代码仓库托管在 GitHub或使用支持 GitHub Actions 的托管平台。被测模块可以在主机环境编译并运行或至少核心逻辑部分可以脱离硬件执行。测试框架已在本地产出可重复执行的命令例如mvn test或pytest。仓库根目录存在可用的构建文件如pom.xml、requirements.txt或pyproject.toml。如果当前仓库还没有任何 CI 配置建议先创建一个.github/workflows目录后续的 YAML 文件都放在该目录下。4. JUnit 接入 GitHub ActionsJUnit 通常配合 Maven 或 Gradle 使用。下面以 Maven 项目为例给出一个最小可用的 GitHub Actions 配置。4.1 创建 workflow 文件在仓库中新建.github/workflows/java-test.yml内容如下name: Java Unit Tests on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Set up JDK 17 uses: actions/setup-javav4 with: distribution: temurin java-version: 17 name: Run unit tests run: mvn test这段配置的含义是当代码推送到main或develop分支或向main发起 Pull Request 时自动在 Ubuntu 环境执行mvn test。任何测试失败都会导致任务失败从而阻止合入。4.2 上传测试报告为了让失败原因更直观可以在测试后上传 JUnit 生成的 XML 报告。修改上述配置增加一个上传步骤- name: Upload test report uses: actions/upload-artifactv4 if: always() with: name: junit-report path: target/surefire-reports/这里使用if: always()确保即使测试失败也会上传报告方便在 Actions 页面下载查看。4.3 缓存依赖加速嵌入式 Java 项目依赖较多每次全量下载会拖慢流水线。可以加入 Maven 依赖缓存- name: Cache Maven dependencies uses: actions/cachev4 with: path: ~/.m2/repository key: ${{ runner.os }}-maven-${{ hashFiles(**/pom.xml) }} restore-keys: | ${{ runner.os }}-maven-缓存命中后后续运行会明显加快。5. pytest 接入 GitHub ActionsPython 侧的动态测试接入方式与 JUnit 类似核心是配置 Python 环境并执行 pytest。下面给出一个适用于嵌入式 Python 模块的配置。5.1 创建 workflow 文件在仓库中新建.github/workflows/python-test.yml内容如下name: Python Unit Tests on: push: branches: [ main, develop ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Set up Python uses: actions/setup-pythonv5 with: python-version: 3.11 name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt pip install pytest name: Run tests run: pytest -v如果项目使用pyproject.toml管理依赖可以把安装步骤改为pip install -e .或pip install .具体取决于项目配置。5.2 指定测试目录嵌入式项目常把测试放在tests目录下与源码分离。此时可以显式指定测试路径- name: Run tests run: pytest tests/ -v如果某些测试依赖硬件或特定环境建议用 pytest 的标记机制跳过而不是让整个流水线失败。例如在测试文件中标记import pytest pytest.mark.hardware def test_uart_send(): ...然后在 CI 中排除该标记- name: Run tests run: pytest tests/ -v -m not hardware这样硬件相关测试留在本地或专门的硬件在环流水线执行主机 CI 只跑纯逻辑测试。6. 失败即拦分支保护配置仅仅在 Actions 中跑测试还不够要让「失败即拦」真正生效还需要在 GitHub 仓库设置分支保护规则。6.1 开启分支保护在仓库页面进入Settings→Branches→Add branch protection rule针对main分支配置勾选Require status checks to pass before merging。在搜索框中选中对应的 workflow 名称例如Java Unit Tests或Python Unit Tests。勾选Require branches to be up to date before merging确保合入前测试基于最新代码。配置完成后任何未通过测试的 Pull Request 都无法合入从机制上实现「失败即拦」。6.2 多测试并行如果仓库同时包含 Java 和 Python 模块可以让两个 workflow 并行执行。GitHub Actions 默认支持多个 workflow 并行无需额外配置。分支保护中可以把两个状态检查都设为必需只有全部通过才允许合入。7. 常见问题与排查接入过程中容易遇到以下几类问题这里给出排查思路。7.1 测试在本地通过、CI 失败最常见的原因是环境差异。排查顺序建议为确认 CI 使用的 JDK 或 Python 版本与本地一致。检查依赖是否完整声明避免依赖本地已安装但未写入配置文件的包。确认测试是否依赖绝对路径或本地环境变量。7.2 硬件相关测试导致 CI 失败如果测试代码直接访问串口、GPIO 或网络设备在 Ubuntu 主机环境必然失败。解决方案是使用 pytest 标记或 JUnit 的Disabled注解把硬件相关用例排除在 CI 之外或单独建立硬件在环流水线。7.3 workflow 文件语法错误YAML 对缩进敏感常见错误包括多一个空格、tab 与空格混用。建议在本地用编辑器校验 YAML 语法或先推送一个空任务验证 workflow 能被正确解析。7.4 测试报告无法下载确认上传步骤使用了if: always()否则测试失败时上传步骤会被跳过。同时检查报告路径是否正确例如 Maven 的target/surefire-reports/或 pytest 的--junitxml输出路径。8. 小结把 JUnit 或 pytest 接入 GitHub Actions本质上是把「本地手动测试」升级为「提交自动测试」。对嵌入式软件而言这一步的价值在于纯逻辑模块的回归测试可以高频、低成本地执行硬件相关问题则通过标记机制分流到专门的测试环境。配合分支保护规则测试失败即阻断合入质量门槛从口头约定变成可执行的门禁。本文给出的配置是入门级的最小方案实际项目中可以根据需要扩展覆盖率统计、静态检查、多平台矩阵等能力。建议先从单个模块试点跑通后再逐步推广到整个仓库。