module Lapis::Docs::B_LAPIS_CLI_AND_TOOLCHAIN::E_TEST_AND_BENCHMARKS

Overview

Testing Framework & Benchmark Suite

Comprehensive guide to running tests and benchmarks with lapis test and lapis bench, including TUI controls, CI mode, memory leak verification, and SVG chart generation.

Executive Summary & Key Topics

Topic Method / Anchor Description
Multi-Tier Testing Architecture .topic_00_testing_phases The four distinct test execution phases orchestrated by lapis test.
lapis test: Options & Flags .topic_01_test_runner_usage Command syntax, filtering by phase, CI non-TTY mode, and TUI toggles.
Interactive TUI Navigation .topic_02_interactive_tui Keyboard controls for the real-time test runner dashboard.
lapis bench: Performance Profiling .topic_03_performance_benchmarks Executing Crystal vs GDScript benchmarks and exporting interactive reports.

Related Guides & Source References

Defined in:

libgodot/docs/b_lapis_cli_and_toolchain/e_test_and_benchmarks.cr

Class Method Summary

Class Method Detail

def self.topic_00_testing_phases : Nil #

Multi-Tier Testing Architecture: The four distinct test execution phases orchestrated by lapis test.

Key Topics & Information

  • Phase 1: Crystal specifications (unit specs in spec/ and tools/lapis/spec/)
  • Phase 2: Headless in-editor @tool tests (ToolTester2D, ToolTester3D)
  • Phase 3: Standalone runtime host suites (40+ suites in spec/suites/)
  • Phase 4: Quantitative zero memory leak verification via assert_no_leak

def self.topic_01_test_runner_usage : Nil #

lapis test: Options & Flags: Command syntax, filtering by phase, CI non-TTY mode, and TUI toggles.

Usage:

lapis test [options]

Options:

Option Description
--tui Force interactive ANSI double-buffered TUI dashboard
--no-tui Force clean linear streaming output (standard for CI environments)
--skip-specs Skip Phase 1 unit specs
--skip-editor Skip Phase 2 headless in-editor tests
--skip-runtime Skip Phase 3 runtime test suites
-f, --filter=PATTERN Run only test cases matching regex pattern

def self.topic_02_interactive_tui : Nil #

Interactive TUI Navigation: Keyboard controls for the real-time test runner dashboard.

When running on an interactive terminal, lapis test launches a split-pane double-buffered dashboard:

Key Action
↑ / k Navigate to previous test phase
↓ / j Navigate to next test phase
Enter / Space Open drill-down log inspection modal for selected phase
Esc / q Close inspection modal or exit runner
? Toggle help overlay

def self.topic_03_performance_benchmarks : Nil #

lapis bench: Performance Profiling: Executing Crystal vs GDScript benchmarks and exporting interactive reports.

Run the performance benchmark harness:

lapis bench [options]

Benchmark Categories:

  • Node Churn: 100,000 node creation, hierarchy reparenting, and destruction.
  • Mathematical Operations: Intensive Vector3, Basis, and Quaternion transforms.
  • Concurrency & Channels: WorkerThreadPool vs Godot::Channel throughput.
  • Signal Churn: High-frequency signal emission and dispatch.

Exporting Visual Reports:

lapis bench run html
# Or configure formats and output path directly:
lapis bench --format=console,html,xml,svg -o reports/