Running tests

Capture test execution and coverage from MSTest, NUnit, and xUnit with the SeaLights .NET Agent.

The examples below assume the self-contained agent package. If you use a framework-dependent package, replace .\sl-dotnet-agent\SL.DotNet.exe or ./sl-dotnet-agent/SL.DotNet with dotnet ./sl-dotnet-agent/SL.DotNet.dll.

Running tests with MSTest, NUnit, or xUnit

You have two ways to capture tests from a supported framework:

• Wrap the test command with the SeaLights agent.
• Use the Profiler-Initiated Collector, or PIC, when you cannot change the startup command.

Minimum System Requirements

• MSTest Framework 1.4.0 (a.k.a. MSTest v2) and higher
• NUnit 3.10.0 and higher
• XUnit 2.3.0 and higher
• VSTest.Console.exe 17.2 and higher

Wrapper to the test command

When you use MSTest, NUnit, or xUnit, wrap the test runner command with the agent. The test listener tracks execution and uploads results automatically.

Here is a sample command with a Lab ID setup.

PowerShell

.\sl-dotnet-agent\SL.DotNet.exe run --tags "mytag" --instrumentationMode tests --labId "<lab-id>" --testStage "Functional Tests" --target "C:\tools\testrunner.exe" --workingDir (Get-Location) --targetArgs "MyTest.dll --flag1 true --flag2 false"

Bash

./sl-dotnet-agent/SL.DotNet run --tags "mytag" --instrumentationMode tests --labId "<lab-id>" --testStage "Functional Tests" --target "/usr/local/bin/testrunner" --workingDir "$(pwd)" --targetArgs "MyTest.dll --flag1 true --flag2 false"

For in-process testing, such as unit or integration tests, remove --instrumentationMode tests or set --instrumentationMode testsAndCoverage.

See Command Reference for full parameter details.

CI examples

These examples wrap dotnet test directly in the pipeline.

Azure DevOps

azure-pipelines.yml

steps:
  - pwsh: |
      .\sl-dotnet-agent\SL.DotNet.exe run `
        --instrumentationMode testsAndCoverage `
        --labId "$(SL_LAB_ID)" `
        --testStage "Unit Tests" `
        --workingDir "$(Build.SourcesDirectory)" `
        --target "dotnet" `
        --targetArgs "test .\tests\MyApp.Tests\MyApp.Tests.csproj --configuration Release"
    displayName: Run .NET tests with SeaLights
    env:
      SL_SESSION_TOKENFILE: $(Pipeline.Workspace)\secrets\sltoken.txt

GitHub Actions

.github/workflows/dotnet.yml

jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run .NET tests with SeaLights
        shell: bash
        env:
          SL_SESSION_TOKENFILE: ./sltoken.txt
          SL_LAB_ID: functional-tests
        run: |
          ./sl-dotnet-agent/SL.DotNet run \
            --instrumentationMode testsAndCoverage \
            --labId "${SL_LAB_ID}" \
            --testStage "Unit Tests" \
            --workingDir "$(pwd)" \
            --target "dotnet" \
            --targetArgs "test ./tests/MyApp.Tests/MyApp.Tests.csproj --configuration Release"

PIC integration

Set the environment variables required for profiling and PIC in the same shell session that runs the tests. In the examples below, SL_AGENT_ROOT is an absolute path to the unpacked agent directory.

• Environment variables should be set in the same session where test runner will be executed.
• Avoid setting PIC or profiling variables system-wide or user-wide. That can attach the profiler to unrelated .NET processes.

PowerShell

$Env:COR_ENABLE_PROFILING = "1"
$Env:COR_PROFILER = "{01CA2C22-DC03-4FF5-8350-59E32A3536BA}"
$Env:COR_PROFILER_PATH_32 = "$SL_AGENT_ROOT\SL.DotNet.ProfilerLib.Windows_x86.dll"
$Env:COR_PROFILER_PATH_64 = "$SL_AGENT_ROOT\SL.DotNet.ProfilerLib.Windows_x64.dll"
$Env:CORECLR_ENABLE_PROFILING = "1"
$Env:CORECLR_PROFILER = "{01CA2C22-DC03-4FF5-8350-59E32A3536BA}"
$Env:CORECLR_PROFILER_PATH_32 = "$SL_AGENT_ROOT\SL.DotNet.ProfilerLib.Windows_x86.dll"
$Env:CORECLR_PROFILER_PATH_64 = "$SL_AGENT_ROOT\SL.DotNet.ProfilerLib.Windows_x64.dll"
$Env:SL_PROFILER_INITIALIZECOLLECTOR = "1"
$Env:SL_PROFILER_INSTRUMENTATIONMODE = "tests"
$Env:SL_SESSION_TOKENFILE = "$SL_AGENT_ROOT\sltoken.txt"
$Env:SL_LABID = "<your_lab_id>"
$Env:SL_GENERAL_TESTSTAGE = "Functional Tests"

Bash

export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER="{3B1DAA64-89D4-4999-ABF4-6A979B650B7D}"
export CORECLR_PROFILER_PATH_64="$SL_AGENT_ROOT/libSL.DotNet.ProfilerLib.Linux.so"
export CORECLR_PROFILER_PATH_32="$SL_AGENT_ROOT/libSL.DotNet.ProfilerLib.Linux.so"
export SL_PROFILER_INITIALIZECOLLECTOR=1
export SL_PROFILER_INSTRUMENTATIONMODE="tests"
export SL_SESSION_TOKENFILE="$SL_AGENT_ROOT/sltoken.txt"
export SL_LABID="<your_lab_id>"
export SL_GENERAL_TESTSTAGE="Functional Tests"

You can now execute the tests in the same session with the regular test command.

dotnet test ./tests/SomeApi.Tests/SomeApi.Tests.csproj --configuration Release

SL_PROFILER_INCLUDEPROCESSFILTER is intentionally omitted. A dotnet test run can start multiple child processes, and a narrow filter can attach to the wrong one.

Set the variables only in the same session that runs the test command.