18
0
mirror of https://github.com/MaSzyna-EU07/maszyna.git synced 2026-11-21 06:14:58 +01:00
Files
maszyna/tests/unit
maj00r 201cae07e1 fix: a failed start says why and ends with an error code; a small crash dump by default (#425)
* fix: a failed start says why in the log and ends with an error code

When the window could not be made, the log only said "Bad init: failed to
create glfw window", without the reason glfw knows (no OpenGL driver, no
pixel format that fits, no EGL). Sometimes it did not even say that: the
log thread writes every 50 ms, and main() ended the process with
std::_Exit(0) without stopping it, so a start that failed within that time
left a log that ends at "// startup".

- glfw's errors go to the log and errors.txt through glfwSetErrorCallback,
  set before glfwInit(); each distinct message once.
- after a failed start (or an exception caught in main) the log thread is
  stopped and waited for, as the test runs already do, so nothing logged
  last is lost.
- a failed start ends with exit code 1 instead of 0, so the starter can
  tell it from a closing. A start that worked ends as before.

* fix: glfw's errors told during the start only, a closed crash dialog is no failed start

After review of the previous commit:

- the glfw error callback is taken off at the end of init(). Once the
  simulator runs, glfw would only repeat what the platform can't do
  (glfwSetCursorPos on Wayland, on every mouse-look) or what a scenery
  asks for in vain (launcher key codes below GLFW_KEY_SPACE, checked on
  every update), which would put new lines in errors.txt of existing
  sceneries and cost a format and a lock per call.
- closing the crash-report window ends the simulator as before, but
  init() now returns 1 for it (above 0: closed by the player), and only a
  result below 0 gives exit code 1.
- a start that throws from init() (bad_alloc, or a runtime_error on
  Windows) ends with exit code 1 too; an exception after a start that
  worked ends with 0 as before.

* feat: a small crash dump by default, the full one with "crashdump.full yes"

The dump written by the crash handler (Windows, WITHDUMPGEN) held all the
memory of the simulator (MiniDumpWithFullMemory), so it was as large as
the memory the simulator took: gigabytes on a large scenery, written to
the game folder at the moment of the crash, on machines with 8 GB of RAM
too.

By default it now holds the stacks with the memory they point to, the
threads, the modules, the handles, the memory map and the modules' data
segments (MiniDumpWithDataSegs in place of MiniDumpWithFullMemory, the
rest of the flags as before). The globals, Global among them, stay
readable. "crashdump.full yes" in eu07.ini writes the full dump as before.

Measured on td.scn with a ghostview camera (1.2 GB committed): the small
dump 44 MB in 2 s, the full one 1.6 GB in 19 s.

The key is new and optional: eu07.ini files without it read as before,
and the setting is listed in the log at start.

* fix: the small crash dump keeps the process and thread blocks

MiniDumpWithProcessThreadData adds the PEB and the TEBs, a few KB: the
command line (the scenery and the vehicle), the environment and the last
error of each thread, which the small dump otherwise lacks, since the heap
behind Global's longer strings is not in it.

* fix: an exception that ends the simulator says what it was in the log

After review of #425:

- the exceptions main() catches are logged ("Critical error: ..."): on
  Windows the runtime_error that only showed a message box, and on the
  other systems any std::exception, which used to end the simulator
  through std::terminate with no word in the log. On Windows the others
  are still left to CrashHandler, whose dump shows where they were
  thrown.
- every exception caught there ends with exit code 1, in the start or
  later, as a crash; it used to be 0 when caught, the abort code when not.
- closing the crash-report window logs "Crash report window closed,
  closing" instead of the error "Failed to run crash gui!", which stays
  for a result below 0.

* feat: the stack of a crash on Linux in the log and on the standard error

On Linux no dump is written (the crash handler is Windows only, crashpad
is off), so a crash left a log that just stopped.

A handler of SIGSEGV, SIGBUS, SIGFPE, SIGILL and SIGABRT (installed at
the start of main) now writes, with write() only:

  Crash: signal 11 (SIGSEGV) at address 0x...
  Version: EU07 (cmake), <hash> (...)
  Stack (addr2line -f -C -e <the eu07 file of this version> <offset>):
  <backtrace_symbols_fd>

to the end of the log file (its whole path, set when the log opens it)
and to the standard error, which StarterNG shows first. The Linux builds
carry their symbols (GENERATE_PDB adds -g, nothing strips them), so
addr2line on the eu07 file of the same version gives the files and lines.

Then the signal ends the process as before (SA_RESETHAND, raise): the
same exit status, and a core dump where the system makes one. The
handler runs on an alternate stack, so an overflow of the main thread's
stack is reported too; backtrace() is warmed up at install so it doesn't
allocate in the handler, and alarm(5) ends a handler that hangs (a crash
in the allocator or the loader). WAMR is built without its hardware bound
checks, so it installs no SIGSEGV handler of its own.

Elsewhere crash_signals does nothing. A unit test (Linux only) crashes a
child process and checks the report on its standard error and in the log,
and that the child still ended by SIGSEGV.

* fix: the crash report can't be cut by a second crash signal or end with SIGALRM

After review:
- the five crash signals are blocked while a report is written, so a
  second one waits rather than starting a second report in its middle
  (a fault that comes while blocked still ends the process).
- a report that hangs past alarm(5) ends the process by the signal of
  the crash, not by SIGALRM: a SIGALRM handler, set only in the crash
  handler, raises the crash signal and unblocks it.
- the child of the unit test calls alarm(10) first, so a child stuck
  before the crash can't hang the build.

---------

Co-authored-by: maj00r <maj00r@host>
2026-11-20 03:53:42 +01:00
..
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00
2026-11-07 12:37:12 +01:00

Unit tests

C++ tests of the simulation logic: set up the conditions, run the code, check the outcome. They run as part of every build of the game, in CI and locally alike, and from the IDE. They need no game data and no window: the test vehicles are JSON definitions in data/, loaded from memory by the game's own vehicle loader.

The code under test is eu07_core, the library of the simulation parts the game links as well (physics, vehicle definition loader, ...): built once, with the game's settings, and tested as the game uses it. The python library gets linked along with the game's settings, but the tests don't use it and run without it.

COVERAGE.md says how much of the simulation core the tests reach, what's left and why, and what they found.

Running

  • With the build: building the game (WITH_TESTS, on by default) runs them at the end, once the game is linked, and prints Unit tests: 11/11 passed (80 checks). A failing test prints the full report and fails the build; the game binary gets removed, so the next build links it again and reruns them. They also run when only the tests, a definition in data/ or run_tests.cmake changed (Ninja and Makefile generators). -DWITH_TESTS=OFF builds the game without them.
  • From the IDE: run or debug the eu07_unit_tests target. CLion recognises doctest and lists the test cases, so a single one can be run or debugged from the gutter.
  • By hand: ctest --test-dir <build dir> --build-config Release, or the binary itself, which takes doctest options, e.g. eu07_unit_tests -tc="brakes*". EU07_UNIT_TESTS_LOG=1 shows the engine log, quiet otherwise.

Writing a test

Add a test_<topic>.cpp here, it's picked up on its own.

#include "stdafx.h"
#include "doctest.h"
#include "vehicle.h"

TEST_CASE("brakes: service braking stops a heavier wagon too") {
	// conditions: the wagon from data/wagon.json, heavier, running at 40 km/h
	test::vehicle wagon{test::definition::load("wagon").set("Param", "M", 60000), 40.0 /* km/h */};
	// action: full service application, as a coupled locomotive would make it
	wagon.hold_brake_pipe(3.5); // bar
	wagon.run(40.0 /* s */, test::track{0.15 /* friction */, 0.0 /* gradient */});
	// outcome
	CHECK(std::abs(wagon.speed()) < 0.1);
}
  • definition::load("<name>") reads data/<name>.json, with the sections and keys of the game's vehicle definitions; set() and remove() change it for the test. Table sections give their rows as "rows": [[...], ...], keys starting with _ are comments. A section the loader doesn't know is an error (the table of them is in fiz.cpp); a misspelt key isn't caught, so check in the test that the value the test is about made it to the vehicle. Keep the definitions physically sensible: some parts need keys others don't (the ESt brake valves need Brake.Size), and a test on a half-defined vehicle tests the definition rather than the simulation.
  • definition::fiz("<dir>/<name>") is one of the game's own vehicles, data/fiz/<dir>/<name>.json, in the same form, converted from the game's .fiz with the files it includes (the list and how to add one: data/fiz/README.md). The conversion keeps what the game's loader reads of the file and checks it reads the same of the converted one (fiz.h), so the vehicle is the game's.
  • The random numbers of the simulation are reseeded before every test case, so a test gives the same result alone or among the others. Loading a vehicle draws some too (the scatter of its brake pipe pressure), so a test making vehicles in a loop calls test::reseed_random() before each.
  • Logic which lives in classes too big to set up in a test (the AI driver, the cab) goes into free functions on the vehicle state the class calls, and the test calls them the same way: see vehicle/handover.h, which TController::TakeControl() uses, and test_handover.cpp.
  • vehicle creates the vehicle the way TDynamicObject::Init() does and steps it the way the simulation loop does, on a straight track of the given friction, gradient, catenary voltage and physics iterations a frame. With a cab (vehicle{definition, 0.0, "name", 1}) it has a driver.
  • consist (consist.h) couples vehicles into a train and steps them together, coupler forces, air, control and power passing between them. The physics reaches a neighbour through its TDynamicObject, for its MoverParameters only; the tests have a stand-in of it with just that.
  • drive.h has the driver's part, made of the AI's steps: start_up() (battery, pumps, pantographs, line breaker, converter, compressor), drive() (running, acknowledging the vigilance), release_brakes(), drive_cycle() (a whole run from start-up to a stop).
  • scenario (scenario.h) puts a train, its driver and a golden trace for each vehicle together, for a test of a feature: act() marks an event in the traces, wait() runs the train.
  • pair (vehicle.h) puts two vehicles on that track facing each other with the given ends and runs them together, as the simulation runs the vehicles of a scene: the coupler and buffer forces, collisions and automatic coupling come from the physics (test_couplers.cpp).
  • A test which reads files makes them in a test::scratch_folder (scratch.h): a folder of its own in the build folder of the tests, removed with the object. The files are written byte for byte, so the line ends are the ones the test gives (test_parser.cpp, test_ladder_logic.cpp).
  • Check behaviour (speeds, pressures, states the player sees) rather than internal flags, and make the test check its own preconditions (REQUIRE that the braking skidded, before checking what a skid leads to).

Golden traces

A golden trace pins down how the simulation behaves now, for changes which mustn't alter it, like restructuring a function: the values of some channels of a vehicle over a run, compared with the ones recorded from the code before, in data/golden/<name>.csv. A difference fails the test, naming the channel, the time and both rows.

The samples and their key figures aren't kept in the repository (tens of megabytes, and they only mean something against the code before the change): record them before the change, and compare after it.

git switch master
EU07_UNIT_TESTS_UPDATE_GOLDEN=1 eu07_unit_tests     # records data/golden/**/*.csv, ignored by git
git switch my-refactor
EU07_UNIT_TESTS_GOLDEN_EXACT=1 eu07_unit_tests      # compares every sample, bit for bit

The recorded files stay through switching branches. Without them, a trace checks the invariants and its test's own CHECKs, which is what the CI does: every test states the behaviour it's about in CHECKs, a scenario of a feature what the feature does (the doors open, the train stops), a run of every real vehicle what holds for each of them (it brakes harder by every step, it runs off and stops).

test::trace trace{"eu07/notch up", test::channels::motion() + test::channels::traction()};
eu07.record(trace); // samples every 10th step
eu07->MainSwitch(true);
trace.mark("main switch"); // shows in the event column of the row
eu07.run(30.0);
trace.check();
  • EU07_UNIT_TESTS_UPDATE_GOLDEN=1 records the samples and the key figures, for a new test or a change which alters the behaviour on purpose; the diff of the key figures shows what it altered, review it like code.
  • Without EU07_UNIT_TESTS_GOLDEN_EXACT=1, samples recorded are compared within a relative 1e-9, as GCC and glibc's maths functions can differ from MSVC's in the last bits, and a trace without them passes. With it they're compared exactly, and a trace without them or its key figures fails, so a run of the refactoring check can't pass by having nothing to compare.
  • Keep the runs short (tens of seconds): the simulation feeds back on itself, and a last bit grows.
  • A trace with no assertion about what the behaviour should be is a characterisation, bugs included; put the behaviour the test is about into CHECKs besides.

Key figures

Next to its samples, every trace records the figures a person reads (figures.h), for each part of the run between two events, in data/golden/<name>.figures: the duration, the speeds, the distance, the time to stop, the brake pipe's lowest pressure and the time to get back to 4.9 bar, the peaks of the brake cylinders, the motor current and the tractive force.

[brake]
duration = 60.00 s
speed at the start = 118.5 km/h
distance = 944.3 m
stopped after = 45.97 s
brake cylinders peak = 3.997 bar

They're compared within 0.5% or the last decimal written, loose enough for any compiler, and the differences are told by part and figure:

key figures of "traction/4e_v1/4e" differ:
  [brake] distance: 944.3 m now, 980.0 m recorded

EU07_UNIT_TESTS_UPDATE_GOLDEN=1 records them with the samples. After a change which alters the behaviour, their comparison says in a few lines what the thousands of changed samples mean. A trace sampled by hand, at times of its own (the commands and switches tests), records none.

Invariants

Every trace also checks, on every step of its vehicle and not only on the recorded ones, the rules which hold for any vehicle whatever a test does (invariants.h): no NaN, the brake cylinders under the vehicle's highest pressure, the pipes under the highest governor setting, no motor current with the line breaker open, no tractive force without power, the distance counted as the speed runs, no acceleration over 5 g, and a few more. They compare nothing with a recorded file, so they hold on any compiler, and they still check a behaviour recorded anew on purpose makes sense. A broken rule fails the test, naming the time, the last event and the values:

invariant "no motor current with the line breaker open" broken in traction/et42 fuse/0 at 63.200 s,
after "dynamic brake": Mains=0 Im=-412.5 Itot=-412.5

Where a test makes a vehicle break a rule (a collision), or a game vehicle breaks one as it is, the list of excuses in invariants.cpp names the trace, the rule and the reason; the second kind goes into the findings of COVERAGE.md too.

A source joins the tested code by moving from SOURCES to CORE_SOURCES in the main CMakeLists.txt; the game links it from the library from then on. The library reaches for a little of the rest of the engine, which engine_stubs.cpp stands in for in the tests (logs, settings, scenery layers). If a change makes it use something new, either move the real source into the library too, when it stands on its own, or add a stub to engine_stubs.cpp.