GitHub Actions Test Logger

🟡 Project status: maintenance mode^[?]

GitHub Actions Test Logger is a custom logger for dotnet test that integrates with GitHub Actions. When using this logger, failed tests are listed in job annotations and highlighted in code diffs. Additionally, this logger also generates a job summary that contains detailed information about the executed test run.

Terms of use^[?]

By using this project or its source code, for any purpose and in any shape or form, you grant your implicit agreement to all the following statements:

• You condemn Russia and its military aggression against Ukraine
• You recognize that Russia is an occupant that unlawfully invaded a sovereign state
• You support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas
• You reject false narratives perpetuated by Russian state propaganda

To learn more about the war and how you can help, click here. Glory to Ukraine! 🇺🇦

Install

• 📦 NuGet: dotnet add package GitHubActionsTestLogger

Screenshots

Usage

To use GitHub Actions Test Logger, install it in your test project and modify your GitHub Actions workflow by adding --logger GitHubActions to dotnet test:

name: main
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Install .NET
        uses: actions/setup-dotnet@v2
        with:
          dotnet-version: 6.0.x

      - name: Build & test
        run: dotnet test --configuration Release --logger GitHubActions

Warning: Ensure that your test project references the latest version of Microsoft.NET.Test.Sdk. Older versions of this package may not be compatible with the logger.

Warning: If you are using .NET SDK v2.2 or lower, you need to set the <CopyLocalLockFileAssemblies> property to true in your test project. Learn more.

Collecting source information

GitHub Actions Test Logger can leverage source information to link reported test results to the locations in the source code where the corresponding tests are defined. By default, dotnet test does not collect source information, so the logger relies on stack traces to extract it manually. This approach only works for failed tests, and even then may not always be fully accurate.

To instruct the runner to collect source information, add the RunConfiguration.CollectSourceInformation=true argument to the command as shown below:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # ...

      - name: Build & test
        # Note that the space after the last double dash (--) is intentional
        run: >
          dotnet test
          --configuration Release
          --logger GitHubActions
          --
          RunConfiguration.CollectSourceInformation=true

Note: This option can also be enabled by setting the corresponding property in a .runsettings file instead. Learn more.

Customizing behavior

When running dotnet test, you can customize the logger's behavior by passing additional options:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # ...

      - name: Build & test
        run: >
          dotnet test
          --configuration Release
          --logger "GitHubActions;annotations.titleFormat=@test;annotations.messageFormat=@error"

Custom annotation title

Use the annotations.titleFormat option to specify the annotation title format used for reporting test failures.

The following replacement tokens are available:

• @test — replaced with the display name of the test
• @traits.TRAIT_NAME — replaced with the value of the trait named TRAIT_NAME
• @error — replaced with the error message
• @trace — replaced with the stack trace
• @framework — replaced with the target framework

Default: @test.

Examples:

• @test → MyTests.Test1
• [@traits.Category] @test → [UI Tests] MyTests.Test1
• @test (@framework) → MyTests.Test1 (.NETCoreApp,Version=v6.0)

Custom annotation message

Use the annotations.messageFormat option to specify the annotation message format used for reporting test failures. Supports the same replacement tokens as annotations.titleFormat.

Default: @error.

Examples:

• @error → AssertionException: Expected 'true' but found 'false'
• @error\n@trace → AssertionException: Expected 'true' but found 'false', followed by stacktrace on the next line

Include passed tests in summary

Use the summary.includePassedTests option to specify whether passed tests should be included in the summary. If you want to link passed tests to their corresponding source definitions, make sure to also enable source information collection.

Default: false.

Include skipped tests in summary

Use the summary.includeSkippedTests option to specify whether skipped tests should be included in the summary. If you want to link skipped tests to their corresponding source definitions, make sure to also enable source information collection.

Default: false.