Skip to content

calionestevar/NexusQA

BranchesTags

Repository files navigation

NexusQA — Modular Testing Framework for Unreal Engine 5

NexusQA Banner

Safety Checks LCARS Demo

A clean, extensible QA automation framework for UE5 featuring parallel execution, distributed tracing, chaos engineering, and compliance testing. Built to demonstrate modern C++ patterns and game industry best practices.

Codename: Project Asgard — A fusion of sci-fi and fantasy universes (Stargate, Star Trek, LOTR, Fringe, Harry Potter, Narnia) powering real-world QA solutions.

🎯 TL;DR — What This Is

For Recruiters: A portfolio project showcasing production-quality C++ for game QA automation. Demonstrates parallel algorithms, distributed tracing, chaos testing, and compliance validation — all using Unreal Engine 5 APIs.

Key Skills Demonstrated:

  • ✅ Modern C++ (RAII, thread-local storage, async patterns, smart pointers)
  • ✅ Unreal Engine 5 (automation framework, memory profiling, HTTP module)
  • ✅ Game Industry Patterns (distributed tracing like Sentry, API testing, performance monitoring)
  • ✅ Clean Architecture (modular design, dependency injection, fluent APIs)

What It Does:

  • Runs game tests in parallel (async task pool) or sequentially (game-thread-only tests)
  • Auto-PIE Launch — Game-thread tests automatically launch PIE and wait for world initialization
  • Conditional Test Skipping — Skip tests based on runtime conditions (network unavailable, feature disabled, platform-specific)
  • Monitors real-time performance metrics (FPS, memory usage, hitches)
  • Live Slate Dashboard — Real-time test status, skipped/passed/failed counters, event monitoring with emojis and color-coding
  • Simulates network chaos (lag injection, packet loss, disconnects)
  • Validates API testing with fluent assertions (REST/GraphQL) with graceful handling for offline scenarios
  • Checks compliance requirements (COPPA/GDPR/DSA)
  • Generates enhanced LCARS reports with test categorization, performance metrics, and skip counts
  • Supports both engine tests and game-specific tests (with UWorld/GameState access)

Tech Stack: C++17, Unreal Engine 5.7, HTTP/JSON APIs, GitHub Actions CI/CD

📋 For Recruiters: View Portfolio Summary — Skills, achievements, and code highlights
📚 For Developers: Continue reading below for technical documentation

🎯 Core Modules

Module Purpose Key Features
Nexus Test orchestration & parallel execution Thread pool execution, fail-fast critical tests, test discovery
Palantír Distributed tracing & API testing Thread-local trace context, REST/GraphQL validation, fluent assertions
LCARSBridge Star Trek-themed HTML/JSON/XML reports LCARS-styled dashboards, artifact generation, multi-format export
FringeNetwork Network chaos engineering Lag injection, packet loss simulation, disconnect testing
StargateStress Load testing & bot simulation Concurrent user simulation, behavior patterns, safety system validation
ArgusLens Performance monitoring Real-time FPS tracking, memory profiling, hitch detection
Protego Compliance & accessibility COPPA/GDPR/DSA checks, color-blind support, subtitle validation
Legacy UE5 AutomationTest integration Commandlet bridge to native automation framework

🚀 Quick Start

Windows (Recommended)

git clone https://github.com/calionestevar/NexusQA
cd NexusQA
.\Scripts\Engage.bat

Linux/macOS

git clone https://github.com/calionestevar/NexusQA
cd NexusQA
./Scripts/RideOut.sh

🔌 Integration as Reusable Framework

Option 1: Git Submodule (Recommended)

Add NexusQA as a plugin to your UE5 project:

cd YourGameProject
git submodule add https://github.com/calionestevar/NexusQA.git Plugins/NexusQA
git commit -m "Add NexusQA testing framework"

Then regenerate your project files and rebuild.

Updating to latest framework:

git submodule update --remote Plugins/NexusQA

Option 2: Manual Copy

Copy the entire Plugins/NexusQA/ folder to your project's Plugins/ directory and rebuild.

Generate Enhanced LCARS Report

# Windows (PowerShell)
.\Scripts\Generate-LCARSTemplate.ps1              # Extract template from C++ source (one-time)
.\Scripts\Generate-LCARSReport.ps1 -OpenInBrowser # Generate sample demo report

# macOS/Linux (Bash)
./Scripts/generate-lcars-template.sh              # Extract template from C++ source (one-time)
./Scripts/generate-lcars-report.sh --open         # Generate sample demo report

Opens Saved/NexusReports/LCARS_Report_<timestamp>.html in your browser with:

  • System Integrity Dashboard — Pass rate %, status bar visualization
  • 4-Column Metrics Grid — Performance, Regression alerts, Memory, Frame diagnostics
  • Test Distribution Cards — Breakdown by 8 framework categories
  • Collapsible Test Sections — Grouped by category with auto-expand for failures
  • Complete Test Listing — Flat table reference of all results

Both scripts generate production-ready sample reports demonstrating all dashboard features.

Template Synchronization Architecture

To keep templates synchronized without manual duplication, we use a Single Source of Truth pattern:

  1. LCARSTemplate.cpp (Source/Nexus/LCARSBridge/Private/)

    • Authoritative HTML template as C++ raw string literal
    • Used by compiled/shipped builds (embedded in binary)

  2. Extract Step (Build-time or development)

    • Run Generate-LCARSTemplate.ps1 or generate-lcars-template.sh
    • Extracts template to LCARSTemplate.html (same folder as C++ source)
    • Both report generation scripts then reference this extracted file

  3. Report Generation Scripts

    • Generate-LCARSReport.ps1 and generate-lcars-report.sh
    • Read the extracted LCARSTemplate.html
    • Inject test data via placeholder token replacement

Update Workflow:

  • Edit template in LCARSTemplate.cpp
  • Run template extraction: Generate-LCARSTemplate.ps1 or generate-lcars-template.sh
  • No need to manually update scripts — they auto-sync via extracted template

This approach mirrors the proven pattern used by ObserverNetworkTemplate for the network dashboard.

📋 What This Framework Produces

Test Artifacts (Saved to Saved/NexusReports/)

  • LCARS_Report_<timestamp>.html — Enhanced Star Trek-themed HTML dashboard with:
    • System Integrity card with pass/fail/skip breakdown
    • Dynamic integrity percentage (calculated from executed tests, excluding skips)
    • 4-metric grid (Performance, Regression, Memory, Frame diagnostics)
    • Test distribution by 8 framework categories
    • Collapsible test sections with auto-expand for failures
    • Complete flat test listing with skip status
  • Slate Live Dashboard (In-Editor while tests run):
    • ⏱️ Uptime counter and frame tracking
    • 🧪 Test Status section: ✓ Passed (green) | ⚠️ Failed (red) | ⏭️ Skipped (gold) | 📊 Total
    • 📋 Recent Events with categorized icons and color-coding
    • 🛡️ Safety Counters tracking custom event types
    • Professional window with configurable sizing and keyboard focus
  • nexus-results.xml — JUnit-style XML for CI/CD integration (includes skip count)
  • test_<name>.log — Per-test execution logs (includes skip reason if applicable)
  • performance_<test>.json — FPS, memory, and hitch metrics
  • accessibility_<test>.json — Compliance check results

CI/CD Integration

GitHub Actions workflows:

  • stone-table.yml ✅ Active — Safety pattern detection (dangerous code patterns)
  • lamppost-beacon.yml ✅ Active — Generates ObserverNetworkDashboard template & LCARS demo report
  • aslan-vigil.yml — Currently disabled (can be re-enabled for test suite execution)
  • cair-paravel.yml — Currently disabled (can be re-enabled for dependency scanning)

🏗️ Architecture Highlights

Parallel Execution

Uses Unreal's Async(EAsyncExecution::ThreadPool) for fast test execution without process overhead.

TArray<TFuture<bool>> Futures;
for (FNexusTest* Test : DiscoveredTests) {
    Futures.Add(Async(EAsyncExecution::ThreadPool, [Test]() {
        return Test->Execute();
    }));
}

Distributed Tracing

Thread-local trace context with automatic ID propagation:

FPalantirTraceGuard TraceGuard; // RAII guard
FString TraceID = FPalantirTrace::GetCurrentTraceID();
// Trace ID automatically flows through nested calls

Fluent API Testing

Readable, chainable assertions for API testing:

PalantirRequest()
    .SetURL("https://api.example.com/users")
    .SetMethod(EHttpMethod::GET)
    .SetTimeout(5.0f)
    .ExpectStatus(200)
    .ExpectHeader("Content-Type", "application/json")
    .ExpectJsonPath("$.users[0].name", "Alice")
    .Send();

Real Performance Monitoring

ArgusLens samples actual UE5 metrics:

float FPS = 1.0f / FApp::GetDeltaTime();
FPlatformMemoryStats MemStats;
FPlatformMemory::GetStatsForMallocProfiler(MemStats);
uint64 UsedMemoryMB = MemStats.UsedPhysical / (1024 * 1024);

📚 Documentation

🚀 Getting Started (Start Here!)

  • Docs/INTEGRATION_GUIDE.md — Using multiple modules together, NEXUS_TEST vs NEXUS_TEST_GAMETHREAD, common patterns, and troubleshooting

Core Framework Guides

Advanced Topics

Development

🛡️ Safety & Security

Tok'Ra Pre-Commit Hook

Prevents commits containing dangerous patterns:

# Install the git hook
.\Scripts\install-tokra.bat  # Windows
./Scripts/install-tokra.sh   # Unix

Blocks:

  • MakeShareable(this) — dangerous shared pointer patterns
  • Hardcoded secrets (API keys, tokens, passwords)
  • Suspicious patterns (shell injection, path traversal)

CI Safety Checks

  • stone-table.yml — Grep-based pattern detection
  • cair-paravel.yml — Dependency vulnerability scanning

🎨 LCARS Report Preview

The framework generates beautiful Star Trek-themed reports featuring:

  • Executive Summary — Pass/fail statistics, execution time
  • API Metrics — Request counts, status codes, response times
  • Performance Data — FPS graphs, memory usage, hitch detection
  • Test Details — Individual results with trace IDs and artifacts

Visual Style:

  • Dark blue gradient background (#000033 → #001155)
  • LCARS color scheme (orange #ff9900, yellow #ffcc00, cyan #00ccff)
  • Monospace "Courier New" font for authenticity
  • Responsive grid layouts for all screen sizes

🧪 Example Test

IMPLEMENT_NEXUS_TEST(FMyGameplayTest)
{
    FPalantirTraceGuard TraceGuard; // Auto trace context
    
    // Performance monitoring
    UArgusLens* Lens = NewObject<UArgusLens>();
    Lens->StartPerformanceMonitoring();
    
    // Test logic
    bool bGameplayPassed = RunGameplayScenario();
    
    // Export results
    Lens->StopPerformanceMonitoring();
    Lens->ExportPerformanceArtifact("MyGameplayTest");
    
    return bGameplayPassed && Lens->DidPassPerformanceGates();
}

📦 Module Dependencies

Nexus
├── Core (Engine, CoreUObject)
├── Palantír (HTTP, Json, JsonUtilities)
└── LCARSBridge (Json)

FringeNetwork → Nexus, Sockets
StargateStress → Nexus, AIModule
ArgusLens → Nexus, Engine
Protego → Nexus, Engine
Legacy → Nexus, AutomationController

🗺️ Roadmap

✅ Recently Completed:

  • Game-thread test execution (NEXUS_TEST_GAMETHREAD macro) — Tests can safely create actors/UObjects
  • Thread-safe test observer with mutex protection (Palantir)
  • Multi-backend dashboard infrastructure (ImGui/Slate/HTML)
  • Test execution context (FNexusTestContext) — Provide UWorld, GameState, PlayerController access
  • Test skip/conditional execution — Skip on platform/configuration basis
  • Automated test retry logic (configurable, exponential backoff)
  • ArgusLens API Integration — Performance assertions in test macros (ASSERT_AVERAGE_FPS, ASSERT_MAX_MEMORY, ASSERT_MAX_HITCHES)
  • ArgusLens Context Integration — Performance metrics attached to FNexusTestContext
  • Performance Test Helper Macros — NEXUS_PERF_TEST for dedicated performance benchmarking
  • Test Timeout Handling — Per-test timeout with MaxDurationSeconds, auto-fail on timeout
  • Test Fixture/Setup/Teardown — BeforeEach/AfterEach callbacks for shared test data
  • Dynamic String-Based Custom Tags — Tag tests with arbitrary categories; reports auto-generate sections for used tags
  • Test Filtering/Tagging System — ETestTag enum, RunTestsWithTags() for CI/CD workflows
  • Failure Stack Trace Capture — Automatic diagnostics on test failure in FNexusTestResult
  • Test Result History & Trend Analysis — DetectRegressions(), ExportTestTrends() for performance baselines
  • Custom Tags System — Project-specific test categorization with AddCustomTag(), HasCustomTag(), GetCustomTags() API
  • Enhanced LCARS Dashboard — 8-metric console-style reporting with System Integrity card, metrics grid, tag distribution, collapsible sections
  • LCARS Template Architecture — Separated reusable HTML template in LCARSBridge module
  • Report Generation Scripts — Both PowerShell and Shell script versions generate production-ready enhanced reports with all dashboard features

Near Term (Foundation for Game Testing):

  • Real-time test execution dashboard (live pass/fail rates, test progress) — Integrate with ObserverNetworkDashboard
  • Test dependencies & ordering system — Handle sequential test requirements beyond priority
  • Smoke test CI workflow for quick validation
  • PIE Auto-Launch — Automatically start Play-in-Editor before game-thread tests

Medium Term (Advanced Testing Features):

  • Blueprint test coverage support — Leverage test context & fixtures
  • Integration with Unreal Insights for deeper profiling
  • Visual regression testing for UI — Requires game-thread screenshot/video capture
  • Screenshot/video capture automation on test failures
  • Custom assertion types & matchers for domain-specific testing
  • Test filtering & tagging system (run subsets by category/platform)
  • Live ImGui overlay during test execution (real-time status visualization)
  • Cross-platform test execution reporting (Linux/macOS in CI)
  • Test parallelization metrics & bottleneck analysis
  • Multiplayer session regression testing (requires test context for multi-actor scenarios)
  • EOS (Epic Online Services) integration testing

Under Consideration:

  • Enhanced chaos injection (CPU throttling, memory pressure)
  • Automated test generation from Blueprint graphs
  • Integration with GameLift for cloud testing
  • Catch2/Google Test framework adapters for hybrid projects
  • Separate Unity QA framework project (future exploration)

🤝 Contributing

See CONTRIBUTING.md for:

  • Code style guidelines
  • Pull request process
  • Testing requirements
  • Documentation standards

📝 License

MIT License — See LICENSE for details.

🌟 Credits

Inspired by:

  • Star Trek (LCARS interface design)
  • Stargate SG-1 (Tok'Ra, Goa'uld, Asgard references)
  • Lord of the Rings (Palantír seeing stones)
  • Fringe (Cortexiphan, parallel universes)
  • Harry Potter (Hogwarts, Protego shield charm)
  • Chronicles of Narnia (Aslan, Cair Paravel)

Built to showcase clean architecture, modern C++ patterns, and game industry integration expertise.

About

A modern testing framework for Unreal Engine 5. NexusQA provides a clean assertion API, modular test architecture, lifecycle hooks, and CI-friendly runners — a more powerful and expressive alternative to UE’s built-in automation system.

Topics

ci-cd unreal-engine gauntlet game-dev sdet automation-testing qa-engineering ue5

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages