running-tests

name	running-tests
description	Describes how to run unit tests, test cases, or performance tests. Invoke this skill whenever running tests for any NEXUS plugin.

Running Tests

Prerequisites

Build the project first. Use the build skill to compile NEXUSEditor if any source files changed.

# Unit tests
& "___UEROOT___\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "___PROJECTROOT___\NEXUS.uproject" -unattended -nopause -testexit="Automation Test Queue Empty" -ReportExportPath="___PROJECTROOT___\Staging\TestResults" -log -ExecCmds="Automation RunTest NEXUS.UnitTests;Quit" -nullrhi

# Functional tests (no -nullrhi: these tests render to screen and require a real graphics context)
& "___UEROOT___\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "___PROJECTROOT___\NEXUS.uproject" -unattended -nopause -testexit="Automation Test Queue Empty" -ReportExportPath="___PROJECTROOT___\Staging\TestResults" -log -ExecCmds="Automation RunTest Tests.Nexus;Quit"

# Performance tests
& "___UEROOT___\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "___PROJECTROOT___\NEXUS.uproject" -unattended -nopause -testexit="Automation Test Queue Empty" -ReportExportPath="___PROJECTROOT___\Staging\TestResults" -log -ExecCmds="Automation RunTest NEXUS.PerfTests;Quit" -nullrhi

Reading Results

The log is the authoritative source of truth — read it, not the JSON report. Always pass -ReportExportPath as an absolute path (___PROJECTROOT___\Staging\TestResults); when relative it resolves against the process working directory and a previous run's index.json is frequently left in place, so a stale file looks like a passing run.

The reliable, always-written record is the log at ___PROJECTROOT___\Saved\Logs\NEXUS.log (the active run; previous runs rotate to NEXUS-backup-<timestamp>.log). Per-test outcomes appear as:

LogAutomationController: Display: Test Completed. Result={Success} Name={...} Path={...}

To confirm a run, grep the log for Result={ — every Result={Success} passed; any Result={Fail failed. This works even when index.json was not refreshed.

The optional report files under Staging/TestResults/:

File	Contents
index.json	Machine-readable results — verify reportCreatedOn is from this run before trusting it (it can be stale; see above)
index.md	Human-readable summary table (only available when run through GitHub actions)
performance.csv	Timer data extracted from perf tests (only present after a perf run through GitHub actions)

Filtering Tests

To run only a specific plugin's tests, narrow the filter prefix:

# Only ActorPools unit tests
& "___UEROOT___\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" "___PROJECTROOT___\NEXUS.uproject" -unattended -nopause -testexit="Automation Test Queue Empty" -ReportExportPath="___PROJECTROOT___\Staging\TestResults" -log -ExecCmds="Automation RunTest NEXUS.UnitTests.NActorPools;Quit" -nullrhi

To run a single test, use its fully-qualified name:

-ExecCmds="Automation RunTest NEXUS::UnitTests::NActorPools::LeakCheck::DontForceDestroy;Quit"

The test name is the string passed as the second argument to the N_TEST_* macro.

Debugging Failures

If a run crashes or tests produce unexpected results, check ___PROJECTROOT___\Saved\Logs\NEXUS.log for Error: or Warning: lines, and the Result={...} line for the specific test. A failed assertion (ADD_ERROR / CHECK_*) is logged immediately before its Test Completed line.