final-vibevault-template/.autograde/workflow_templates/README.md

Workflow 模板

本目录包含不同编程语言的 Gitea Actions workflow 模板。

可用模板

文件	语言	容器	测试框架
python.yml	Python	python:3.11	pytest
java.yml	Java	maven:3.9-eclipse-temurin-17	JUnit 5
r.yml	R	r-base:4.3	testthat

使用方法

1. 选择模板

根据你的编程语言选择对应的模板：

# 对于 Python 作业
cp .autograde/workflow_templates/python.yml .gitea/workflows/grade.yml

# 对于 Java 作业
cp .autograde/workflow_templates/java.yml .gitea/workflows/grade.yml

# 对于 R 作业
cp .autograde/workflow_templates/r.yml .gitea/workflows/grade.yml

2. 自定义配置

编辑 .gitea/workflows/grade.yml 根据需要修改：

• 容器版本：修改 container: 字段
• 超时时间：修改 timeout-minutes:
• 依赖安装：修改 "Install dependencies" 步骤
• 测试命令：修改测试运行步骤

3. 配置 Secrets

确保在 Gitea 仓库设置中配置了以下 Secrets：

• TESTS_TOKEN：用于访问隐藏测试仓库的 token（可选）
• EXTERNAL_GITEA_HOST：外部访问的 Gitea 地址（可选）

Python 模板 (python.yml)

特点

• 使用 python:3.11 容器
• 自动安装 requirements.txt 中的依赖
• 使用 run_tests.py 运行 pytest
• 支持代码覆盖率

自定义选项

# 修改 Python 版本
container: python:3.10  # 或 python:3.9

# 添加额外的依赖
- name: Install dependencies
  run: |
    pip install -r requirements.txt
    pip install numpy pandas  # 额外的包    

Java 模板 (java.yml)

特点

• 使用 maven:3.9-eclipse-temurin-17 容器
• Maven 自动管理依赖（通过 pom.xml）
• JUnit 5 测试框架
• 自动提取 Surefire 报告

自定义选项

# 修改 JDK 版本
container: maven:3.9-eclipse-temurin-11  # Java 11
container: maven:3.9-eclipse-temurin-21  # Java 21

# 自定义 Maven 命令
run: |
  mvn clean test -B -DskipTests=false  

Maven 配置提示

确保 pom.xml 中配置了 Surefire 插件：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.2</version>
    <configuration>
        <reportsDirectory>${project.build.directory}/surefire-reports</reportsDirectory>
    </configuration>
</plugin>

R 模板 (r.yml)

特点

• 使用 r-base:4.3 容器
• 自动从 DESCRIPTION 安装依赖
• testthat 测试框架
• JUnitReporter 输出 XML

自定义选项

# 修改 R 版本
container: r-base:4.2  # 或其他版本

# 修改 CRAN 镜像
run: |
  Rscript -e "install.packages('testthat', repos='https://cran.r-project.org/')"  

R 项目结构要求

project/
├── DESCRIPTION         # 包依赖定义
├── R/                  # R 源代码
└── tests/
    └── testthat/       # testthat 测试

通用 Workflow 流程

所有模板都遵循相同的流程：

1. 安装系统依赖（git, rsync 等）
2. 检出代码 - 克隆学生仓库
3. 安装语言依赖 - 根据语言安装包
4. 获取隐藏测试（可选）- 从私有仓库获取
5. 运行测试 - 生成 JUnit XML
6. 评分 - 解析 XML，计算分数
7. 生成元数据 - 创建 JSON metadata
8. 发布评论 - 在 PR 中发布结果

高级配置

添加代码质量检查

- name: Run linter
  run: |
    # Python: pylint, flake8
    pip install pylint
    pylint src/
    
    # Java: checkstyle
    mvn checkstyle:check
    
    # R: lintr
    Rscript -e "lintr::lint_package()"    

自定义评分规则

修改 grade.py 的调用参数：

- name: Grade
  run: |
    python3 ./.autograde/grade.py \
      --junit junit.xml \
      --out grade.json \
      --summary summary.md \
      --bonus bonus.json  # 可选的加分项    

多个测试套件

- name: Run public tests
  run: |
    pytest tests_public/ --junit-xml=public.xml    

- name: Run hidden tests
  run: |
    pytest tests_hidden/ --junit-xml=hidden.xml    

- name: Merge test results
  run: |
    python3 ./.autograde/merge_junit.py public.xml hidden.xml -o junit.xml    

故障排查

测试无法运行

• 检查测试目录路径是否正确
• 确认依赖是否正确安装
• 查看 Actions 日志中的错误信息

JUnit XML 未生成

• Python: 确保 pytest 命令包含 --junit-xml
• Java: 检查 Surefire 插件配置
• R: 确认 testthat >= 3.0.0

元数据为空

• 检查 grade.json 是否生成
• 确认 LANGUAGE 环境变量设置正确
• 查看 create_minimal_metadata.py 的输出

相关文档

• 运行测试脚本 - 通用测试运行器
• 评分脚本 - JUnit XML 解析和评分
• 元数据生成 - JSON 元数据
• 示例 - 各语言的完整示例

---

最后更新: 2025-11-13