> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/running-tests.md).

# Running tests

{% hint style="info" %}
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`.
{% endhint %}

## Running tests with MSTest, NUnit, or xUnit <a href="#running-tests-with-mstest-nunit-or-xunit" id="running-tests-with-mstest-nunit-or-xunit"></a>

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.

{% hint style="warning" %}
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
  {% endhint %}

### Wrapper to the test command <a href="#wrapper-to-the-test-command" id="wrapper-to-the-test-command"></a>

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.

{% tabs %}
{% tab title="PowerShell" %}
{% code overflow="wrap" lineNumbers="true" %}

```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"
```

{% endcode %}
{% endtab %}

{% tab title="Bash" %}
{% code overflow="wrap" lineNumbers="true" %}

```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"
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
For in-process testing, such as unit or integration tests, remove `--instrumentationMode tests` or set `--instrumentationMode testsAndCoverage`.
{% endhint %}

{% hint style="info" %}
See [Command Reference](/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/command-reference.md) for full parameter details.
{% endhint %}

### CI examples <a href="#ci-examples" id="ci-examples"></a>

These examples wrap `dotnet test` directly in the pipeline.

{% tabs %}
{% tab title="Azure DevOps" %}
{% code title="azure-pipelines.yml" overflow="wrap" %}

```yaml
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
```

{% endcode %}
{% endtab %}

{% tab title="GitHub Actions" %}
{% code title=".github/workflows/dotnet.yml" overflow="wrap" %}

```yaml
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"
```

{% endcode %}
{% endtab %}
{% endtabs %}

### PIC integration <a href="#pic-integration" id="pic-integration"></a>

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.

{% hint style="warning" %}

* 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.
  {% endhint %}

{% tabs %}
{% tab title="PowerShell" %}
{% code overflow="wrap" lineNumbers="true" %}

```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"
```

{% endcode %}
{% endtab %}

{% tab title="Bash" %}
{% code overflow="wrap" lineNumbers="true" %}

```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"
```

{% endcode %}
{% endtab %}
{% endtabs %}

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

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

{% hint style="info" %}
`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.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/.net-core-agent/running-tests.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.