bugfix/unittest & adds github actions

.github/README.md

@@ -0,0 +1,11 @@
+# GitHub Actions 配置文件
+
+此目录包含 GitHub Actions 工作流配置文件。
+
+## 文件说明
+
+- `test.yml` - 单元测试工作流
+- `publish.yml` - PyPI 发布工作流
+- `README.md` - 配置说明文档
+
+详细说明请查看 [README.md](README.md)

.github/workflows/README.md

@@ -0,0 +1,189 @@
+# GitHub Actions 配置说明
+
+本项目使用 GitHub Actions 进行自动化测试和发布。
+
+## 📋 工作流列表
+
+### 1. 单元测试 (`test.yml`)
+
+**触发条件**:
+- 推送到 `main` 分支
+- 向 `main` 分支提交 Pull Request
+
+**测试矩阵**:
+- Python 3.9, 3.10, 3.11, 3.12, 3.13
+- Ubuntu Latest
+
+**执行内容**:
+1. 检出代码
+2. 设置 Python 环境（多版本）
+3. 安装项目和开发依赖
+4. 运行单元测试（pytest）
+5. 生成覆盖率报告
+6. 上传覆盖率到 Codecov（仅 Python 3.11）
+
+### 2. 发布到 PyPI (`publish.yml`)
+
+**触发条件**:
+- 推送 tag（格式：`v*.*.*`，如 `v0.3.0`）
+
+**执行内容**:
+1. 检出代码
+2. 设置 Python 环境
+3. 构建分发包
+4. 发布到 TestPyPI（测试）
+5. 发布到 PyPI（正式）
+6. 创建 GitHub Release
+
+---
+
+## 🔐 配置 Secrets
+
+在 GitHub 仓库中配置以下 Secrets：
+
+### 必需的 Secrets
+
+1. **`PYPI_API_TOKEN`** - PyPI API Token
+   - 获取地址: https://pypi.org/manage/account/token/
+   - 用途: 发布到正式 PyPI
+
+2. **`TESTPYPI_API_TOKEN`** - TestPyPI API Token
+   - 获取地址: https://test.pypi.org/manage/account/token/
+   - 用途: 发布到 TestPyPI 测试
+
+### 可选的 Secrets
+
+3. **`CODECOV_TOKEN`** - Codecov Token
+   - 获取地址: https://codecov.io/
+   - 用途: 上传测试覆盖率报告
+
+### 配置步骤
+
+1. 进入 GitHub 仓库
+2. Settings → Secrets and variables → Actions
+3. 点击 "New repository secret"
+4. 添加上述 Secrets
+
+---
+
+## 🚀 使用方法
+
+### 运行测试
+
+推送代码到 `main` 分支即可自动触发测试：
+
+```bash
+git add .
+git commit -m "Update code"
+git push origin main
+```
+
+### 发布新版本
+
+1. **更新版本号**
+   ```bash
+   # 编辑 pyproject.toml
+   version = "0.3.1"
+
+   # 编辑 src/debug_helpers/__init__.py
+   __version__ = "0.3.1"
+
+   # 更新 CHANGELOG.md
+   ```
+
+2. **提交更改**
+   ```bash
+   git add pyproject.toml src/debug_helpers/__init__.py CHANGELOG.md
+   git commit -m "Bump version to 0.3.1"
+   git push origin main
+   ```
+
+3. **创建 tag 并推送**
+   ```bash
+   git tag v0.3.1
+   git push origin v0.3.1
+   ```
+
+4. **自动发布**
+   - GitHub Actions 会自动触发
+   - 先发布到 TestPyPI
+   - 再发布到 PyPI
+   - 创建 GitHub Release
+
+---
+
+## 📊 查看结果
+
+### 测试结果
+- 访问: `https://github.com/<username>/<repo>/actions`
+- 查看 "Python Unit Tests" 工作流
+
+### 覆盖率报告
+- 访问: `https://codecov.io/gh/<username>/<repo>`
+- 查看详细覆盖率报告
+
+### 发布状态
+- 访问: `https://github.com/<username>/<repo>/actions`
+- 查看 "Publish to PyPI" 工作流
+- 查看 Releases 页面
+
+---
+
+## 🔧 本地测试 Actions
+
+使用 [act](https://github.com/nektos/act) 在本地测试 GitHub Actions：
+
+```bash
+# 安装 act
+brew install act  # macOS
+# 或
+curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+# 测试 test.yml
+act push
+
+# 测试 publish.yml
+act push --eventpath .github/workflows/event.json
+```
+
+---
+
+## 📝 注意事项
+
+### 测试工作流
+- ✅ 测试多个 Python 版本以确保兼容性
+- ✅ 使用 `fail-fast: false` 确保所有版本都被测试
+- ✅ 仅在 Python 3.11 上传覆盖率报告（避免重复）
+
+### 发布工作流
+- ⚠️ 发布是不可逆的操作
+- ⚠️ 确保版本号在 `pyproject.toml` 和 `__init__.py` 中保持一致
+- ⚠️ 相同版本号无法重新上传到 PyPI
+- ✅ 先发布到 TestPyPI 可以预先测试
+- ✅ 使用 `--skip-existing` 避免 TestPyPI 重复上传错误
+
+### Token 安全
+- 🔒 永远不要在代码中硬编码 Token
+- 🔒 使用 GitHub Secrets 管理敏感信息
+- 🔒 Token 应设置合适的权限范围
+
+---
+
+## 🎯 工作流状态徽章
+
+在 README.md 中添加徽章：
+
+```markdown
+![Tests](https://github.com/<username>/<repo>/workflows/Python%20Unit%20Tests/badge.svg)
+![PyPI](https://img.shields.io/pypi/v/debug-helpers.svg)
+![Coverage](https://codecov.io/gh/<username>/<repo>/branch/main/graph/badge.svg)
+```
+
+---
+
+## 🔗 相关链接
+
+- [GitHub Actions 文档](https://docs.github.com/en/actions)
+- [Python GitHub Actions](https://github.com/actions/setup-python)
+- [PyPI Publishing with GitHub Actions](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)
+- [Codecov](https://codecov.io/)

.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+# 发布到 PyPI - 创建新 tag 时自动触发
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'  # 匹配 v0.1.0, v1.2.3 等格式的 tag
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: 检出代码
+      uses: actions/checkout@v4
+
+    - name: 设置 Python 环境
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: 安装构建工具
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: 构建分发包
+      run: |
+        python -m build
+
+    - name: 检查分发包
+      run: |
+        twine check dist/*
+
+    - name: 发布到 TestPyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.TESTPYPI_API_TOKEN }}
+      run: |
+        twine upload --repository testpypi dist/* --skip-existing
+
+    - name: 发布到 PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        twine upload dist/*
+
+    - name: 创建 GitHub Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: dist/*
+        generate_release_notes: true
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,56 @@
+# Python 项目单元测试 - 推送到 main 分支时自动运行
+name: Python Unit Tests
+
+on:
+  push:
+    branches: [main]  # 仅在推送到 main 分支时触发
+  pull_request:
+    branches: [main]  # 也可在 PR 时运行
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+      fail-fast: false  # 一个版本失败不影响其他版本继续测试
+
+    steps:
+    - name: 检出代码
+      uses: actions/checkout@v4
+
+    - name: 设置 Python ${{ matrix.python-version }} 环境
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'  # 自动缓存 pip 依赖
+
+    - name: 显示 Python 版本
+      run: |
+        python --version
+        pip --version
+
+    - name: 升级 pip
+      run: |
+        python -m pip install --upgrade pip
+
+    - name: 安装项目和开发依赖
+      run: |
+        pip install -e '.[dev]'
+
+    - name: 显示已安装的包
+      run: |
+        pip list
+
+    - name: 运行单元测试
+      run: |
+        pytest tests/ -v --cov=src/debug_helpers --cov-report=term-missing --cov-report=xml
+
+    - name: 上传覆盖率报告到 Codecov
+      if: success() && matrix.python-version == '3.11'
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}
+        files: ./coverage.xml
+        fail_ci_if_error: false
+        verbose: true

Makefile

@@ -89,7 +89,17 @@ uninstall:
 # 运行单元测试
 test:
 	@echo "==> 运行单元测试..."
-	pytest tests/ -v
+	@echo ""
+	@if command -v pytest >/dev/null 2>&1; then \
+		echo "使用 pytest 运行测试..."; \
+		pytest tests/ -v; \
+	else \
+		echo "使用 unittest 运行测试..."; \
+		python -m unittest discover -s tests -v; \
+	fi
+	@echo ""
+	@echo "💡 提示: 安装 pytest 可以获得更好的测试体验"
+	@echo "   pip install -e '.[dev]'"
 
 # 运行示例代码
 example: