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

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

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

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.