Ctrlk
Contact SupportProduct
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Capturing Test Events (Windows / MSVC)

Overview

Per-test event capture enables Test Impact Analysis (TIA). SeaLights identifies tests that cover each code path. It can skip tests unaffected by a change.

This page covers three paths:

  1. Scenario 1 — In-process GTest (GTest IS the AUT): The run command captures coverage and test events together.

  2. Scenario 2 — External GTest test framework: GTest drives a remote AUT. The background listener receives pass, fail, and skip events.

  3. Scenario 3 — Non-GTest frameworks (NUnit, MSTest, XUnit, JUnit): Upload the XML report after the test run. The AUT listener captures coverage separately. See Application Under Test.

Prerequisite for GTest scenarios

Pass integrateMsBuild --gtest during the MSBuild integration step. The command injects the GTest event-listener shim into application projects that resolve <gtest/gtest.h>.

Without the shim, GTest does not report test events.

Scenario 1: In-process unit tests

The GTest binary is both the test framework and the AUT. Use the run command as shown in Application Under Test → Mode 1. The command captures coverage and test events in one process.

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
}

run sets PATH for the tracer DLL automatically. You need no further configuration.

Scenario 2: External GTest test framework

GTest drives a remote AUT in a separate process. Start a background listener before the GTest binary runs. The GTest event-listener shim connects automatically and reports pass, fail, and skip events.

Add the agent directory to PATH first:

The listener returns immediately after startBackgroundTestListener. Any instrumented GTest binary on the same host connects to <Port> and reports events automatically.

Parallel GTest stages: Use a distinct --agentPort and --testListenerSessionKey for each listener. Pass the same key to startBackgroundTestListener and stopBackgroundTestListener. Each listener and stage pair needs its own startExecution and endExecution.

To capture AUT coverage with GTest test events, run a second listener for the AUT. See Application Under Test → Mode 2, Option B. The listeners can share a port and stage, or use separate ports for independent control.

Scenario 3: Non-GTest frameworks

After the test run completes, upload the XML report. The AUT listener already collects coverage. See Application Under Test → Mode 2.

--file accepts one XML file or a folder of report files. Frameworks with JUnit XML output use the same path. This includes Playwright with its JUnit reporter and Tosca.

Add --useExistingExecution when the AUT listener stage already manages startExecution and endExecution.

Next step: Parameter Reference

PreviousApplication Under Test (Windows / MSVC)NextC++ Agent Parameter Reference (Windows)

Last updated

Was this helpful?