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.

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.

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.

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
}

Azure DevOps

- 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
      }

For per-test granularity and Test Impact Analysis with GTest, see Capturing Test Events.

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:

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

Option A: Wrap the AUT with run

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

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
}

Azure DevOps

- 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
      }

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.

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
}

Azure DevOps

- 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

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.

Next step: Capturing Test Events