Development and testing
How to build Gym.NET, run its two test suites, and add to them. The rules for contributors' code are in the repository's CLAUDE.md; the parity suite's own guide is tests/Gym.Tests.Parity/CLAUDE.md.
Prerequisites
The .NET 11 SDK (11.0.100 or later) with the .NET 8 and .NET 10 runtimes: the libraries target
net8.0,net10.0andnet11.0, the unit tests and the Windows Forms viewer the three-windowsforms. An older SDK builds and testsnet8.0andnet10.0alone, sincenet11.0joins only on an SDK that can build it (decision D24), and a release build (-p:ContinuousIntegrationBuild=true) refuses such an SDK (GYMNET0011,Directory.Build.targets).The two reference submodules, initialized without
--recursive(that would also clone NumSharp's own submodules, which the build doesn't need):git submodule update --init refs/Gymnasium refs/NumSharprefs/Gymnasiumis Gymnasium v1.4.0 (8ba8c3a6), the behavior Gym.NET is held to.refs/NumSharpis NumSharp v0.80.0's source, used only by the opt-in-p:NumSharpSource=Submodulebuild; the default build uses the NumSharp 0.81.0 package.For the parity suite only: Python 3.12 with NumPy 2.4.2, pygame-ce 2.5.8, Box2D 2.3.10, OpenCV 4.13.0 and MuJoCo 4.0.0, the stack pinned in
tools/parity/manifest.json.pwsh tools/parity/setup_venv.ps1(orbash tools/parity/setup_venv.sh) creates it intools/parity/.venv, where the suite finds it. A venv made before the MuJoCo envs (2026-11-12) lacksmujoco, and the stack check then fails every cell: run the script again.Set
AVALONIA_TELEMETRY_OPTOUT=1: building the Avalonia projects otherwise sends Avalonia's build telemetry.
Build
dotnet build Gym.NET.sln -c Debug
dotnet build Gym.NET.sln -c Release
The solution holds the five packaged libraries (src/Gym, src/Gym.Rendering, src/Gym.Environments,
src/Gym.Rendering.Avalonia, src/Gym.Rendering.WinForm), the source generator (src/Gym.SourceGenerators), the test
projects and examples/CartPole. Building the libraries also packs them (GeneratePackageOnBuild): a release build is
dotnet build src/<project>/<project>.csproj -c Release -p:ContinuousIntegrationBuild=true -p:PackageOutputPath=<folder>
for each of the five. Build rather than dotnet pack: with GeneratePackageOnBuild the Pack target skips the build, so
dotnet pack on a fresh clone stops with NU5026, the DLLs to pack not existing yet.
The unit suite: tests/Gym.Tests
MSTest, headless, no Python. It holds Gymnasium's own pytest files rewritten in C# under tests/Gym.Tests/Gymnasium
(one file per Python file, test_core.py → TestCore.cs), plus Gym.NET's own tests.
# The gate: everything except the viewer tests, which open windows, and the known gaps
dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName!~AvaloniaEnv&FullyQualifiedName!~WinFormEnv&TestCategory!=OpenBugs"
# One framework, one class, one test
dotnet test tests/Gym.Tests/Gym.Tests.csproj -f net10.0-windows --filter "FullyQualifiedName~ToyTextTests"
dotnet test tests/Gym.Tests/Gym.Tests.csproj --filter "FullyQualifiedName~TestMake.TestMakeWithEnvSpecLevels"
-f net10.0 (without -windows) matches no target framework of the unit project and silently runs nothing.
The parity suite: tests/Gym.Tests.Parity
The suite embeds CPython through pythonnet, imports Gymnasium from refs/Gymnasium, and runs both libraries side by
side with the same seeds and actions. Each cell compares dtypes, shapes and bytes of arrays, IEEE-754 bits of floats,
info keys in order, exception types and messages, the PCG64 generator state, and rgb_array frames pixel for pixel.
There is no tolerance.
# The gate
dotnet test tests/Gym.Tests.Parity/Gym.Tests.Parity.csproj --filter "TestCategory!=OpenBugs"
# The known gaps, each printing its first divergence from Gymnasium
dotnet test tests/Gym.Tests.Parity/Gym.Tests.Parity.csproj --filter "TestCategory=OpenBugs" --logger "console;verbosity=detailed"
# The recorded trajectories, replayed without Python (what the Linux CI job runs)
dotnet test tests/Gym.Tests.Parity/Gym.Tests.Parity.csproj --filter "TestCategory=Golden"
- Goldens (
tests/Golden): trajectories and frames the live cells verified, recorded withGYMNET_PARITY_RECORD=1and replayed without Python, so machines without the stack still check the envs. - The reverse bridge (
tests/Gym.Tests.Parity/Bridge): Gym.NET's envs exposed to Python as Gymnasium envs, so Gymnasium's owncheck_envandcheck_environments_matchrun on them. - Failed frames write
python.png,dotnet.pnganddiff.pngto the test results (orGYMNET_PARITY_ARTIFACTS).
Known gaps: [OpenBugs]
A test Gym.NET does not pass yet carries [OpenBugs("id")], NumSharp's convention: the gated runs exclude it, and a
plain dotnet test runs it and fails. The id names the reason: N-x a NumSharp gap (docs/plans/COMPLETION_PLAN.md §7;
N-1 to N-4 closed with NumSharp 0.81.0), DR-xx a documented divergence such as DR-46's Intel IPP bilinear, B-xx the
defect register of the port plan.
The expectation is always Gymnasium's answer, never today's output: when the gap closes, the test passes, and the
attribute is removed so it becomes part of the gate. A deliberate, documented deviation is not an open bug; it is a
gated test that pins the deviation.
The name inventory
tests/Gym.Tests/Gymnasium/inventory.expected-missing.txt lists every public Gymnasium name Gym.NET has no counterpart
for yet, each with its reason. A test fails when a listed name appears (remove the line) or an unlisted one is missing,
so the list only shrinks.
Writing code here
- Every member is documented with what it does, what it costs and its footguns: each parameter, return value and
exception. A member based on Gymnasium's source links it as a pinned permalink in
<remarks>, for exampleReference: <see href="https://github.com/Farama-Foundation/Gymnasium/blob/8ba8c3a63bb4e000b7f33923f43d292acac07be1/gymnasium/core.py#L28">gymnasium/core.py</see>.The docs describe Gym.NET's own members in its own voice. - Exceptions: Python's built-ins come from NumSharp (
ValueError,TypeError,KeyError,AssertionError), Gymnasium's fromGym.Exceptions; messages are Gymnasium's, verbatim. - Rewards are
doubleeverywhere. - Arrays are disposed by whoever owns them. NumSharp's analyzer reports an array created and dropped (
NDW012);Gym.RenderingandGym.Tests.Paritytreat warnings as errors, so there it fails the build. - A behavior change comes with a live parity cell that compares it with Gymnasium, and a new comparison rule in the
harness with a self-test that plants a defect and checks it is caught (
Tests/Harness/HarnessSelfTests.cs).
CI
.github/workflows/ci.yml builds the solution in Debug and Release on Windows, runs the unit gate, sets up the parity
stack and runs the parity gate; a Linux job builds the parity suite and replays the goldens. Until 1.0 it runs on the
working branch and is informational.