Unit Testing#

Unit testing is a powerful tool that helps to achieve and maintain a solid code quality. For it to be effective, unit tests should be tied to the development cycle and run automatically, so that during the development, one can directly check the outcome of the unit tests without having to take care of initiating them.

A suitable approach for such automated setup is to use CI/CD pipelines. This project templates has a unit testing pipeline set up and here are all you need to know bout it:

File location: .github/workflows/unitTests.yml

This GitHub Actions workflow is for running Python unit tests and reporting test coverage directly on Pull Requests.

With uv and the py-cov-action, this workflow is highly optimized for speed and automated feedback.

Here is the breakdown of exactly what this workflow does, section by section.

1. The Triggers (on)#

This section dictates when the workflow runs.

  • Push: It triggers on direct pushes to the main branch.

  • Pull Request: It triggers when PRs targeting main are opened, updated (synchronize), reopened, edited, or marked as “ready for review”.

2. Job 1: unit-tests#

This job handles the actual execution of your testing suite.

  • The Guardrail (if): Even though the workflow triggers on pushes to main, this specific job is explicitly restricted to Pull Requests only, and it strictly ignores Draft Pull Requests. If someone opens a draft, it won’t waste runner minutes.

  • Setup & Checkout: It checks out your code on an ubuntu-24.04 machine and explicitly pulls in any Git submodules if you have them.

  • Environment Setup (The Modern Way): Instead of using standard setup-python and pip, it uses astral-sh/setup-uv@v7 to install uv with automatic caching. Then, it runs uv sync --group test to instantly create the environment and fetch dependencies based on your pyproject.toml.

  • Execution: It runs pytest via uv run.

  • -s: Disables output capturing (shows print statements).

  • -vvv: Maximum verbosity.

  • --cov: Measures code coverage.

  • It sets an environment variable to name the coverage file .coverage.unittests.

  • Artifact Storage: Regardless of whether the tests pass or fail (if: always()), it takes the generated .coverage.unittests file and uploads it to GitHub’s temporary storage so the next job can access it.

3. Job 2: coverage#

This job takes the results from the first job, analyzes them, and posts a comment on the Pull Request.

  • Dependencies (needs): It waits for unit-tests to finish. It will run whether the tests passed or failed, ensuring you still get a coverage report even if a test breaks.

  • Permissions: It grants the GitHub Actions bot permission to write comments on PRs and read repository contents.

  • Download & Combine: It downloads the coverage artifact uploaded in the previous step. The merge-multiple: true flag is a great touch—if you ever expand this workflow to run tests on multiple operating systems or Python versions, this will combine all their coverage files together.

  • The Commenter: It uses python-coverage-comment-action to parse the .coverage file and automatically post (or update) a highly visual comment on the active Pull Request showing exactly which lines of code were covered or missed.

  • Fallback Storage: It saves the raw text of the comment as an artifact. This is often used in advanced setups where PRs from forks don’t have permission to comment directly, allowing a separate workflow to post it later.

This setup is:

  1. Cost-efficient: It entirely skips Draft PRs.

  2. Fast: It relies on uv for dependency resolution, which shaves significant time off the setup phase compared to standard pip.

  3. Decoupled: By separating the test running from the coverage reporting, you keep the logs clean and make it easier to add more testing jobs (like integration tests or UI tests) later without rewriting the coverage logic.