Implementation:Farama Foundation Gymnasium Check Environments Match

Knowledge Sources	Farama_Foundation_Gymnasium Gymnasium Docs
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,
)

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime