GitHub Integration

Integrating Erbsland Unit Test with GitHub Actions allows you to automatically build and test your project on each push or pull request. This ensures that all contributions meet quality standards and pass unit tests before being merged.

Verify CTest Activation

Ensure that CTest is enabled in your CMake project and configured to run the unittest target. Add the following lines to your main CMakeLists.txt:

cmake_minimum_required(VERSION 3.23)
project(ExampleUnitTest)

add_subdirectory(erbsland-unittest)
add_subdirectory(example-lib)
add_subdirectory(unittest)

# Activate CTest
enable_testing()
add_test(
    NAME unittest
    COMMAND $<TARGET_FILE:unittest> --no-color
)

This configuration registers a test named unittest, which executes your unit test binary using CTest. The --no-color flag ensures clean log output in CI environments like GitHub Actions.

Create the Workflow File

To enable this integration, create a new workflow file named ci.yml (or alternatively unittest.yml) inside your repository under the path .github/workflows. This file defines a GitHub Actions workflow that sets up the build environment, compiles your project, and runs the tests.

Here is a complete example of such a workflow:

name: CI

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      BUILD_DIR: cmake-build

    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Cache CMake build
        uses: actions/cache@v3
        with:
          path: ${{ env.BUILD_DIR }}
          key: ${{ runner.os }}-cmake-${{ hashFiles('**/CMakeLists.txt') }}

      - name: Install apt deps
        run: |
          sudo apt-get update
          sudo apt-get install -y build-essential cmake ninja-build

      - name: Configure
        run: cmake -S . -B ${{ env.BUILD_DIR }} -G Ninja -DCMAKE_BUILD_TYPE=Debug

      - name: Build
        run: cmake --build ${{ env.BUILD_DIR }} --config Debug

      - name: Run tests
        run: |
          cd ${{ env.BUILD_DIR }}
          ctest --output-on-failure

Step-by-Step Explanation

This workflow is designed to automatically build and test your project using GitHub-hosted runners. Let’s go through each section:

Workflow Trigger

on:
  push:
    branches: [ main ]
  pull_request:

The workflow is triggered on two events:

• When a commit is pushed to the main branch.

• When a pull request is opened or updated.

These triggers ensure that both direct changes and proposed changes are verified.

Job Definition

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      BUILD_DIR: cmake-build

A single job named build is defined. It runs on the latest Ubuntu runner and uses an environment variable BUILD_DIR to store build artifacts in a dedicated subdirectory.

Checkout the Repository

- uses: actions/checkout@v4
  with:
    submodules: recursive

This step checks out your source code, including all Git submodules, which are often used for test frameworks or dependencies.

Cache the Build

- name: Cache CMake build
  uses: actions/cache@v3
  with:
    path: ${{ env.BUILD_DIR }}
    key: ${{ runner.os }}-cmake-${{ hashFiles('**/CMakeLists.txt') }}

To speed up repeated builds, this step caches the cmake-build directory. The cache is keyed by the operating system and the contents of all CMakeLists.txt files. If nothing changed in those files, the cached build output can be reused.

Install Dependencies

- name: Install apt deps
  run: |
    sudo apt-get update
    sudo apt-get install -y build-essential cmake ninja-build

Installs required packages for building the project using CMake and Ninja. This is typically needed for C++ development environments on CI runners.

Configure the Build

- name: Configure
  run: cmake -S . -B ${{ env.BUILD_DIR }} -G Ninja -DCMAKE_BUILD_TYPE=Debug

Runs CMake to configure the project using the Ninja generator. The build type is set to Debug to include debugging symbols and enable assertions in your unit tests.

Build the Project

- name: Build
  run: cmake --build ${{ env.BUILD_DIR }} --config Debug

Builds the project using the previously configured Ninja setup. The --config flag is mostly relevant for multi-config generators, but including it keeps the setup consistent.

Run the Tests

- name: Run tests
  run: |
    cd ${{ env.BUILD_DIR }}
    ctest --output-on-failure

Navigates to the build directory and runs your test suite using ctest. The --output-on-failure flag ensures that, if any test fails, the output is shown in the GitHub Actions log for easy debugging.

Final Outcome

With this setup in place, your unit tests will automatically run every time:

• a new commit is pushed to the main branch, or

• a pull request is opened or updated.

This ensures continuous validation of your codebase, helping to catch regressions early and maintain high quality standards throughout development.