Testing

Test architecture

LandSandBoat has a custom test framework built into the xi_test binary. Tests are written in Lua using a BDD-style describe/it API, and the test runner is a dedicated process (src/test/) that spins up a full in-memory MapEngine and WorldEngine against a live database.

xi_test
├── src/test/           # C++ test runner
│   ├── test_engine.cpp # Discovers and runs Lua test suites
│   ├── test_collector.cpp
│   ├── test_suite.cpp
│   ├── test_case.cpp
│   └── lua/            # Lua-side test helpers (CLuaSimulation, etc.)
└── scripts/tests/      # Lua test files
    ├── framework/      # Test framework self-tests and helpers
    ├── systems/        # Game system tests (combat, spells, latents, etc.)
    ├── jobs/           # Per-job ability and trait tests
    ├── missions/       # Mission progress tests
    └── packets/        # Packet output verification tests

Running tests locally

With Docker (recommended)

The dev.docker-compose.yml test service runs xi_test against a containerized MariaDB:

# Build and run the test suite
docker compose -f dev.docker-compose.yml run --build test

# Results are written to log/tests.ctrf.json (CTRF format)

The --keep-going flag ensures all tests run even if some fail.

Without Docker

Build xi_test with CMake and run it directly:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --target xi_test --parallel

./build/xi_test --keep-going
./build/xi_test --keep-going --output log/tests.ctrf.json

xi_test requires a running MariaDB instance with a populated database. Use environment variables to configure the connection:

export XI_NETWORK_SQL_HOST=localhost
export XI_NETWORK_SQL_DATABASE=xidb
export XI_NETWORK_SQL_LOGIN=xiadmin
export XI_NETWORK_SQL_PASSWORD=password

Writing Lua tests

Test files live under scripts/tests/ and use a describe/it BDD API. The test runner discovers all .lua files in that tree automatically.

Basic test structure

describe('My Feature', function()
    it('does the thing correctly', function()
        ---@type CClientEntityPair
        local player = xi.test.world:spawnPlayer({
            zone  = xi.zone.WEST_RONFAURE,
            job   = xi.job.WHM,
            level = 75,
        })

        -- Assert the player spawned in the right zone
        player.assert:inZone(xi.zone.WEST_RONFAURE)

        -- Assert job
        assert(player:getMainJob() == xi.job.WHM, 'Expected job to be WHM')
    end)
end)

Lifecycle hooks

describe('Lifecycle example', function()
    ---@type CClientEntityPair
    local player

    setup(function()
        -- Runs once before the describe block
        player = xi.test.world:spawnPlayer({
            zone = xi.zone.WEST_RONFAURE,
            job  = xi.job.WHM,
        })
    end)

    before_each(function()
        -- Runs before each it() in this describe block
        player:setLevel(75)
    end)

    after_each(function()
        -- Runs after each it()
    end)

    teardown(function()
        -- Runs once after all tests in the describe block
    end)

    it('has WHM job', function()
        assert(player:getMainJob() == xi.job.WHM)
    end)

    it('is level 75', function()
        assert(player:getMainLvl() == 75)
    end)
end)

CClientEntityPair

xi.test.world:spawnPlayer(...) returns a CClientEntityPair — a coupled (client, server entity) pair that lets you drive the player from the Lua test:

-- Spawn a player
local player = xi.test.world:spawnPlayer({
    zone = xi.zone.PORT_SAN_DORIA,
    new  = true,  -- treat as new character
})

-- Assertions
player.assert:inZone(xi.zone.PORT_SAN_DORIA)
player.assert:hasItem(xi.item.ONION_SWORD)
player.assert:hasKI(xi.ki.MAP_OF_THE_SAN_DORIA_AREA)
player.assert:hasGil(10)

-- Entity interaction
player.entities:gotoAndTrigger('Regine', { eventId = 510 })
player:gotoZone(xi.zone.WEST_RONFAURE)

-- Find another entity
local rabbit = player.entities:moveTo('Wild_Rabbit')
assert(rabbit)

Test specs (type definitions)

scripts/specs/ contains Lua type definition files (LuaLS annotations) for all binding types. These are picked up by the Lua Language Server and provide autocomplete and type checking in editors:

scripts/specs/core/
├── CBaseEntity.lua
├── CZone.lua
├── CSpell.lua
├── CStatusEffect.lua
├── CBattlefield.lua
└── ...
scripts/specs/test/
├── CSimulation.lua
├── CTestEntity.lua
├── CClientEntityPair.lua
└── ...

Startup checks

The startup_checks service (run as python -m tools.ci.startup_checks) validates that the server can start cleanly — including zone initialization, Lua loading, and basic sanity checks — without running the full test suite.

docker compose -f dev.docker-compose.yml run --build startup_checks

Static analysis — clang-tidy

clang-tidy runs as a separate build in CI and locally via Docker:

docker compose -f dev.docker-compose.yml run --build clang_tidy
# Output: log/clang_tidy_summary.md

The enabled checks are defined in .clang-tidy at the repository root. See Code style for the full list.

CI workflows

CI is handled by GitHub Actions. The relevant workflows are:

Workflow	File	Trigger
Builds	`build.yml`	Push to `base`
Tests	`test.yml`	After `Builds` succeeds
PR Checks	`pr_checks.yml`	Pull request
CodeQL	`codeql_analysis.yml`	Push to `base`
Docker Build	`docker_build.yml`	Called from `build.yml`
Docker Test	`docker_test.yml`	Called from `test.yml`

Build matrix

The Builds workflow compiles on:

OS	Compiler	Build type
Ubuntu 24.04	GCC 14	Debug
Ubuntu 24.04	Clang 20	Debug (+ clang-tidy)
Windows 2025	MSVC	Debug + Release
macOS 26	Apple Clang	Debug + Release
Docker (Ubuntu)	GCC 14	Release
Docker (Alpine)	Clang 20	Release

Test matrix

The Tests workflow runs after a successful build:

Sanity checks — shell-based checks run against origin/base
Lua Language Server — type-checks all Lua scripts
Runner tests — xi_test on Windows and macOS
Docker tests — xi_test + startup checks on Ubuntu and Alpine containers

All of these checks can be run locally using dev.docker-compose.yml services before pushing. See Development workflow for service names and commands.

Contributing

Architecture

Tools

Test architecture

Running tests locally

With Docker (recommended)

Without Docker

Writing Lua tests

Basic test structure

Lifecycle hooks

CClientEntityPair

Test specs (type definitions)

Startup checks

Static analysis — clang-tidy

CI workflows

Build matrix

Test matrix

​Test architecture

​Running tests locally

​With Docker (recommended)

​Without Docker

​Writing Lua tests

​Basic test structure

​Lifecycle hooks

​CClientEntityPair

​Test specs (type definitions)

​Startup checks

​Static analysis — clang-tidy

​CI workflows

​Build matrix

​Test matrix

Test architecture

Running tests locally

With Docker (recommended)

Without Docker

Writing Lua tests

Basic test structure

Lifecycle hooks

CClientEntityPair

Test specs (type definitions)

Startup checks

Static analysis — clang-tidy

CI workflows

Build matrix

Test matrix