> 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/c++-agent/c++-agent-for-windows-beta/application-under-test-windows-msvc.md).

# Application Under Test (Windows / MSVC)

This page covers two deployment modes for running an instrumented binary with SeaLights coverage collection:

* **Mode 1 — In-process unit tests:** GTest is the AUT. The GTest binary acts as both the test framework and the code under test in one process. Use the `run` command. GTest is currently the only supported in-process test framework.
* **Mode 2 — Functional testing:** The AUT runs in a separate process from the test framework. The test framework can use GTest, NUnit, Playwright, Tosca, or another tool. Wrap the AUT with `run`, or start a background listener when you cannot change the AUT startup command.

### Required runtime files

Keep these files available wherever the instrumented binary runs:

* **`.slmap` file** — The scan produces this file. Keep it in the same directory as its `.exe`. It contains the build-specific RVA-to-function-name map. Generate it again after every rebuild.
* **`sltracer_x64.dll` or `sltracer_x86.dll`** — Use the DLL that matches your build architecture. The `run` command adds the agent directory to `PATH`. For externally launched tests, add the agent directory to `PATH` yourself or copy the DLL beside the binary.
* **SeaLights agent package** — Keep the package available at test time for the tracer DLLs and agent commands.

{% hint style="warning" %}
Keep instrumented testing builds and production builds separate. The `/Gh` tracer adds a function-entry callback to every instrumented function. This overhead does not suit production.
{% endhint %}

### Mode 1: In-process unit tests

Use this mode when the GTest binary is the code under test. The `run` command launches the binary as a child process, sets `PATH` for the tracer DLL, and exits when the child exits.

{% tabs %}
{% tab title="PowerShell" %}

```powershell
SL.Agent.Cpp.exe startExecution `
  --tokenFile          ./sltoken.txt `
  --labId              ci-main-mycppapp `
  --buildSessionIdFile buildSessionId.txt `
  --testStage          Unit-Tests

try {
  SL.Agent.Cpp.exe run `
    --tokenFile          ./sltoken.txt `
    --labId              ci-main-mycppapp `
    --buildSessionIdFile buildSessionId.txt `
    --testStage          Unit-Tests `
    --target             .\bin\Release\MyCppApp.Tests.exe `
    --targetArgs         "--gtest_output=xml:.\TestResults\results.xml"
} finally {
  SL.Agent.Cpp.exe endExecution `
    --tokenFile          ./sltoken.txt `
    --labId              ci-main-mycppapp `
    --buildSessionIdFile buildSessionId.txt `
    --testStage          Unit-Tests
}
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- task: PowerShell@2
  displayName: Run in-process GTest binary with coverage
  env:
    SL_TOKEN: $(SL_TOKEN)
  inputs:
    targetType: inline
    script: |
      SL.Agent.Cpp.exe startExecution --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Unit-Tests
      try {
        SL.Agent.Cpp.exe run --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Unit-Tests --target .\bin\Release\MyCppApp.Tests.exe --targetArgs "--gtest_output=xml:.\TestResults\results.xml"
      } finally {
        SL.Agent.Cpp.exe endExecution --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Unit-Tests
      }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For per-test granularity and Test Impact Analysis with GTest, see Capturing Test Events.
{% endhint %}

### Mode 2: Functional testing

The AUT runs in a separate process. Your test framework drives it externally. You can use NUnit, Playwright, Tosca, GTest, or another framework.

Add the tracer DLL directory to `PATH` before you launch the AUT:

```powershell
$env:PATH = "C:\SealightsAgent;$env:PATH"
```

#### Option A: Wrap the AUT with `run`

Use this option when you can modify the AUT startup command.

{% tabs %}
{% tab title="PowerShell" %}

```powershell
SL.Agent.Cpp.exe startExecution `
  --tokenFile          ./sltoken.txt `
  --labId              ci-main-mycppapp `
  --buildSessionIdFile buildSessionId.txt `
  --testStage          Functional-Tests

try {
  SL.Agent.Cpp.exe run `
    --tokenFile          ./sltoken.txt `
    --labId              ci-main-mycppapp `
    --buildSessionIdFile buildSessionId.txt `
    --testStage          Functional-Tests `
    --target             .\bin\Release\MyCppApp.exe `
    --targetArgs         "--serve"
  # Run your test framework in a separate step or terminal
} finally {
  SL.Agent.Cpp.exe endExecution `
    --tokenFile          ./sltoken.txt `
    --labId              ci-main-mycppapp `
    --buildSessionIdFile buildSessionId.txt `
    --testStage          Functional-Tests
}
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- task: PowerShell@2
  displayName: Run functional AUT with coverage
  env:
    SL_TOKEN: $(SL_TOKEN)
  inputs:
    targetType: inline
    script: |
      SL.Agent.Cpp.exe startExecution --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Functional-Tests
      try {
        SL.Agent.Cpp.exe run --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Functional-Tests --target .\bin\Release\MyCppApp.exe --targetArgs "--serve"
      } finally {
        SL.Agent.Cpp.exe endExecution --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Functional-Tests
      }
```

{% endtab %}
{% endtabs %}

#### Option B: Background listener (recommended)

Use this option when the AUT must start normally without modification. Common examples include Windows services, Docker-hosted processes, and CI environments with fixed startup commands.

{% tabs %}
{% tab title="PowerShell" %}

```powershell
SL.Agent.Cpp.exe startExecution `
  --tokenFile          ./sltoken.txt `
  --labId              ci-main-mycppapp `
  --buildSessionIdFile buildSessionId.txt `
  --testStage          Functional-Tests

SL.Agent.Cpp.exe startBackgroundTestListener `
  --tokenFile          ./sltoken.txt `
  --labId              ci-main-mycppapp `
  --buildSessionIdFile buildSessionId.txt `
  --testStage          Functional-Tests `
  --agentPort          31031

try {
   # AUT launches normally — tracer auto-connects to listener
   .\deploy\MyCppApp.exe
} finally {
   SL.Agent.Cpp.exe stopBackgroundTestListener `
     --tokenFile          ./sltoken.txt `
     --buildSessionIdFile buildSessionId.txt `
     --agentPort          31031
   SL.Agent.Cpp.exe endExecution `
     --tokenFile          ./sltoken.txt `
     --labId              ci-main-mycppapp `
     --buildSessionIdFile buildSessionId.txt `
     --testStage          Functional-Tests
}
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- task: PowerShell@2
  displayName: Start execution and background listener
  env:
    SL_TOKEN: $(SL_TOKEN)
  inputs:
    targetType: inline
    script: |
      SL.Agent.Cpp.exe startExecution --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Functional-Tests
      SL.Agent.Cpp.exe startBackgroundTestListener --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Functional-Tests --agentPort 31031

- task: PowerShell@2
  displayName: Launch AUT and run functional tests
  inputs:
    targetType: inline
    script: |
      Start-Process .\deploy\MyCppApp.exe
      .\tests\Run-FunctionalTests.ps1

- task: PowerShell@2
  displayName: Stop listener and end execution
  condition: always()
  env:
    SL_TOKEN: $(SL_TOKEN)
  inputs:
    targetType: inline
    script: |
      SL.Agent.Cpp.exe stopBackgroundTestListener --token $env:SL_TOKEN --buildSessionIdFile buildSessionId.txt --agentPort 31031
      SL.Agent.Cpp.exe endExecution --token $env:SL_TOKEN --labId ci-main-mycppapp --buildSessionIdFile buildSessionId.txt --testStage Functional-Tests
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
AUT coverage hits are collected regardless of the test framework that drives the AUT. For GTest test event capture, see Capturing Test Events Scenario 2. For NUnit, MSTest, xUnit, or JUnit test event capture, see Capturing Test Events Scenario 3.
{% endhint %}

Next step: Capturing Test Events


---

# 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/c++-agent/c++-agent-for-windows-beta/application-under-test-windows-msvc.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.