Implementation:Farama Foundation Gymnasium Check Environments Match
| Knowledge Sources | |
|---|---|
| Domains | Reinforcement_Learning, Environment_Testing |
| Last Updated | 2026-02-15 03:00 GMT |
Overview
A testing utility that verifies two Gymnasium environments produce identical outputs when given the same seed and actions over a specified number of steps.
Description
The check_environments_match function provides a deterministic comparison of two environment instances (env_a and env_b) by seeding them identically and running them through the same sequence of actions. It verifies equivalence across multiple dimensions: observations, rewards, terminated signals, truncated signals, info dictionaries, and rendered outputs.
The function supports several comparison modes for info dictionaries via the info_comparison parameter: "equivalence" (exact match), "superset" (env_b's info contains all of env_a's keys with matching values), "keys-equivalence" (same keys, ignoring values), "keys-superset" (env_b has at least all of env_a's keys), and "skip" (no info comparison). Individual comparison dimensions (observations, rewards, terminal, truncated, render) can be selectively disabled via boolean skip_* parameters.
The function handles episode boundaries by resetting both environments when either reports a terminal or truncated signal, and re-validates the reset observations. It uses the data_equivalence utility from gymnasium.utils.env_checker for array-safe comparisons.
Usage
Use this function when testing that a refactored or JAX-accelerated environment implementation produces the same results as the original reference implementation, or when verifying that environment wrappers preserve expected behavior.
Code Reference
Source Location
- Repository: Farama_Foundation_Gymnasium
- File:
gymnasium/utils/env_match.py
Signature
def check_environments_match(
env_a: gym.Env,
env_b: gym.Env,
num_steps: int,
seed: int = 0,
skip_obs: bool = False,
skip_rew: bool = False,
skip_terminal: bool = False,
skip_truncated: bool = False,
skip_render: bool = False,
info_comparison: str = "equivalence",
) -> None
Import
from gymnasium.utils.env_match import check_environments_match
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| env_a | gymnasium.Env | Yes | First environment to compare |
| env_b | gymnasium.Env | Yes | Second environment to compare |
| num_steps | int | Yes | Number of timesteps to test (0 tests only reset) |
| seed | int | No | Seed for reset and action sampling (default 0) |
| skip_obs | bool | No | Skip observation equivalence checks (default False) |
| skip_rew | bool | No | Skip reward equivalence checks (default False) |
| skip_terminal | bool | No | Skip terminated signal checks (default False) |
| skip_truncated | bool | No | Skip truncated signal checks (default False) |
| skip_render | bool | No | Skip render output checks (default False) |
| info_comparison | str | No | Info comparison mode: "equivalence", "superset", "keys-equivalence", "keys-superset", or "skip" |
Outputs
| Name | Type | Description |
|---|---|---|
| (none) | None | Raises AssertionError if environments do not match |
Usage Examples
import gymnasium as gym
from gymnasium.utils.env_match import check_environments_match
# Compare two environment implementations
env_a = gym.make("CartPole-v1")
env_b = gym.make("CartPole-v1")
check_environments_match(env_a, env_b, num_steps=100, seed=42)
# Compare with partial checks (skip info)
check_environments_match(
env_a, env_b,
num_steps=50,
info_comparison="skip",
skip_render=True,
)