Testing

The harness

PyTorch uses its own test harness, layered on top of unittest. From CLAUDE.md:

from torch.testing._internal.common_utils import run_tests, TestCase

class TestFeature(TestCase):
    def test_something(self):
        ...

if __name__ == "__main__":
    run_tests()

Why a custom harness? The harness adds:

• Per-test seeding for reproducibility.
• Better tensor comparison (assertEqual handles dtype/shape/device).
• Per-device test instantiation.
• Test parameterization.
• Automatic skip / xfail for unsupported configurations.

The harness lives in torch/testing/_internal/common_utils.py.

Tensor comparisons

self.assertEqual(actual, expected)             # tensor or scalar
self.assertEqual(actual, expected, atol=1e-3, rtol=1e-3)
self.assertEqual(actual, expected, exact_dtype=False)
self.assertNotEqual(a, b)

assertEqual understands tensors, scalars, sequences, dicts, and named tuples. Don't roll your own torch.allclose checks in tests — they don't get the fp16/bf16 default tolerances right.

Parametrization

from torch.testing._internal.common_utils import parametrize, instantiate_parametrized_tests

class TestFoo(TestCase):
    @parametrize("dtype", [torch.float32, torch.bfloat16])
    @parametrize("shape", [(3,), (3, 4), (3, 4, 5)])
    def test_bar(self, dtype, shape):
        ...

instantiate_parametrized_tests(TestFoo)

The decorator generates one test method per (dtype, shape) combination. Names become e.g. test_bar_dtype_torch_float32_shape_3_4.

Per-device tests

Tests that should run across CPU, CUDA, MPS, XPU, etc. should use instantiate_device_type_tests:

from torch.testing._internal.common_device_type import instantiate_device_type_tests
from torch.testing._internal.common_utils import TestCase, run_tests

class TestFooBase(TestCase):
    def test_something(self, device):
        x = torch.zeros(3, device=device)
        ...

instantiate_device_type_tests(TestFooBase, globals())

This generates TestFooCPU, TestFooCUDA, TestFooMPS, TestFooXPU, etc. each running the test with the appropriate device. Use the related decorators to opt in/out:

@dtypes(torch.float32, torch.bfloat16)
@onlyCUDA
@skipIfRocm
@skipMeta
@skipCUDAIfNoMagma
def test_linalg_thing(self, device, dtype): ...

Defined in torch/testing/_internal/common_device_type.py.

OpInfo

For an op-level test that should automatically cover all sample inputs, supported dtypes, and gradient checks, register an OpInfo in torch/testing/_internal/common_methods_invocations.py:

OpInfo(
    "my_op",
    op=torch.my_op,
    sample_inputs_func=sample_inputs_my_op,
    supports_forward_grad=True,
    supports_fwgrad_bwgrad=True,
    dtypes=floating_types_and(torch.bfloat16, torch.float16),
    skips=(...),
)

test_ops.py, test_ops_gradients.py, and test_ops_fwd_gradients.py then test your op for free with the full battery of correctness, gradient, and serialization checks.

Running tests

# Default subset
python test/run_test.py

# Specific files
python test/run_test.py -i test_torch test_nn

# Direct invocation
python test/test_torch.py -v
python test/test_torch.py TestTorch.test_addmm

# pytest also works
pytest test/test_torch.py -k matmul

# C++ tests (after build with BUILD_TEST=1)
build/bin/test_api

Compile / inductor tests

These have their own subdirectory:

python test/inductor/test_torchinductor.py
python test/dynamo/test_misc.py
python test/test_compile.py

The compiler test suites are large; expect to filter aggressively with -k.

Distributed tests

Distributed tests use a multi-process spawner that runs each test_* method across N processes:

python test/distributed/test_c10d_nccl.py
python test/distributed/_tensor/test_dtensor.py
python test/distributed/fsdp/test_fsdp_grad_acc.py

Most distributed tests require multiple GPUs. They auto-skip if not enough are available.

Writing tests for new ops

The standard recipe:

1. Add the op to aten/src/ATen/native/native_functions.yaml.
2. Add a derivative to tools/autograd/derivatives.yaml if differentiable.
3. Add an OpInfo to torch/testing/_internal/common_methods_invocations.py.
4. Add a "small" test file (e.g., test/test_my_op.py) for op-specific edge cases.
5. Update OpInfo skips for known limitations on specific backends/dtypes.

OpInfo coverage gives you several thousand correctness-check test runs for free.

Where to look

File	Purpose
torch/testing/_internal/common_utils.py	Harness
torch/testing/_internal/common_device_type.py	Per-device test instantiation
torch/testing/_internal/common_methods_invocations.py	OpInfo definitions
torch/testing/_internal/distributed/	Distributed test harness
test/run_test.py	Top-level test runner