feat: add test coverage reporting with GitHub Pages badge (#62)

* chore: add coverage configuration to pyproject.toml

Configure pytest-cov with:
- Branch coverage enabled for stackone_ai source
- Exclusions for __init__.py and py.typed files
- Standard exclusion patterns (TYPE_CHECKING, NotImplementedError, etc.)
- JSON output to coverage/coverage.json for CI badge generation
- HTML output to coverage/html for detailed reports

* chore: add coverage command to justfile

Add `just coverage` command that runs pytest with:
- Terminal coverage report for quick feedback
- JSON report for CI badge generation
- HTML report for detailed analysis

* chore: ignore coverage output files

Add .coverage and coverage/ to .gitignore to prevent
committing locally generated coverage reports.

* ci: add coverage reporting with GitHub Pages deployment

Add coverage job that runs on main branch pushes:
- Run tests with pytest-cov to generate coverage reports
- Generate coverage badge using coverage-badges-cli
- Upload coverage artifacts to GitHub Pages

Add deploy-coverage job to publish reports to GitHub Pages,
making coverage badge and HTML report publicly accessible at
https://stackonehq.github.io/stackone-ai-python/

Matches the coverage setup in stackone-ai-node repository.

* docs: add coverage badge to README

Display test coverage percentage badge that links to
the detailed HTML coverage report on GitHub Pages.

Author: ryoppippi

.github/workflows/ci.yaml

@@ -12,6 +12,8 @@ concurrency:
 
 permissions:
   contents: read
+  pages: write
+  id-token: write
 
 jobs:
   typos:
@@ -59,3 +61,46 @@ jobs:
 
       - name: Run Tests
         run: nix develop --command just test
+
+  coverage:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    env:
+      STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Setup Nix
+        uses: ./.github/actions/setup-nix
+
+      - name: Install dependencies
+        run: nix develop --command just install --all-extras
+
+      - name: Run Tests with Coverage
+        run: nix develop --command just coverage
+
+      - name: Create Coverage Badge
+        uses: jaywcjlove/coverage-badges-cli@bd6ccbf422c0ed54c01f283019fd2bc648f58541 # v2.2.0
+        with:
+          source: coverage/coverage.json
+          output: coverage/badges.svg
+          jsonPath: totals.percent_covered
+
+      - name: Upload coverage artifact
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v3.0.2
+        with:
+          path: coverage/
+
+  deploy-coverage:
+    needs: coverage
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -5,6 +5,8 @@
 .pytest_cache
 .python-version
 __pycache__
+.coverage
+coverage/
 
 .DS_Store
 

README.md

@@ -2,6 +2,7 @@
 
 [![PyPI version](https://badge.fury.io/py/stackone-ai.svg)](https://badge.fury.io/py/stackone-ai)
 [![GitHub release (latest by date)](https://img.shields.io/github/v/release/StackOneHQ/stackone-ai-python)](https://github.com/StackOneHQ/stackone-ai-python/releases)
+[![Coverage](https://stackonehq.github.io/stackone-ai-python/badges.svg)](https://stackonehq.github.io/stackone-ai-python/html/)
 
 StackOne AI provides a unified interface for accessing various SaaS tools through AI-friendly APIs.
 

justfile

@@ -14,6 +14,10 @@ lint-fix:
 test:
 	uv run pytest
 
+# Run tests with coverage
+coverage:
+	uv run pytest --cov --cov-report=term --cov-report=json --cov-report=html
+
 # Run tool-specific tests
 test-tools:
 	uv run pytest tests

pyproject.toml

@@ -123,3 +123,26 @@ ignore_missing_imports = true
 module = "mcp.*"
 ignore_missing_imports = true
 ignore_errors = true
+
+[tool.coverage.run]
+source = ["stackone_ai"]
+branch = true
+omit = [
+    "stackone_ai/__init__.py",
+    "**/py.typed",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if typing.TYPE_CHECKING:",
+]
+
+[tool.coverage.json]
+output = "coverage/coverage.json"
+
+[tool.coverage.html]
+directory = "coverage/html"