Refactor Test Decoupling

Classification

Every test falls into one of three categories. Classification is hierarchical: device-specific > device-agnostic > CPU-only.

Device API Categories (consult ../../../reference/device_api_catalog.yaml)

Only Category C makes a test device-specific. If you can replace "cuda" with "mps" or "xpu" and the test still makes logical sense, it's device-agnostic.

Blacklist vs. Whitelist Decorators

@onlyNativeDeviceTypes / @onlyNativeDeviceTypesAnd are redundant on device-agnostic classes — device instantiation already scopes to the right devices. REMOVE them (the test linter flags them on ACCELERATOR classes).

Decision Tree

Does the test reference a device?
├─ NO → CPU-only
├─ YES → What device APIs?
│  ├─ Generic only (torch.device(device), make_tensor(..., device=device)) → device-agnostic
│  ├─ Category A or B APIs → device-agnostic
│  ├─ Category C APIs → device-specific
│  └─ Hard to tell → Leave as-is

What decorators?
├─ Blacklist (@skipXPU, @skipCUDAIf, @skipMPS, @skipMeta) → KEEP
├─ Whitelist (@onlyCUDA, @onlyOn, @unittest.skipIf(not TEST_CUDA, ...)) → ENLARGE to @onlyAccelerator

> **Note:** An `if device_type == "<backend>"` conditional in the test body does NOT make a test device-specific — only Category C API calls do.

False-CUDA Patterns (→ device-agnostic, NOT device-specific)

These almost always indicate device-agnostic:

Caveats:

• Do NOT enlarge @onlyCUDA → @onlyAccelerator if the test had no prior device restriction — remove the restriction entirely instead.
• Keep @onlyCUDA if the test relies on backend-specific behavioral guarantees (NaN handling, determinism, precision, rounding modes).

Strategy: CPU-only

Zero device dependency. CPU tensors only, no device parameter.

Pattern A — Plain TestCase (no parametrization):

from torch.testing._internal.common_utils import HardwareClassification

class TestFoo(TestCase):
    hw_classification = HardwareClassification.GENERIC

    def test_basic_addition(self):
        a = torch.randn(3, 3)
        b = torch.randn(3, 3)
        self.assertEqual(a + b, torch.add(a, b))

Pattern B — @instantiate_parametrized_tests (has @parametrize/@ops/@dtypes):

from torch.testing._internal.common_utils import HardwareClassification

@instantiate_parametrized_tests
class TestFoo(TestCase):
    hw_classification = HardwareClassification.GENERIC

    @parametrize("dtype", [torch.float32, torch.float64])
    def test_dtype_behavior(self, dtype):
        t = torch.randn(3, 3, dtype=dtype)
        self.assertEqual(t.softmax(0).sum(0), torch.ones(3, dtype=dtype))

Why not instantiate_device_type_tests? It creates per-device variants (TestFooCPU, TestFooCUDA, etc.) — wasteful when all variants do the same CPU-only work.

Steps:

1. Extract test methods into a standalone class. Keep the original name (no device suffix) — CPU-only classes should never have device suffixes.
2. Remove device parameter from signatures; hardcode "cpu" or omit device args
3. Remove device decorators and device imports (TEST_CUDA, TEST_MPS, etc.)
4. Add @instantiate_parametrized_tests if the class has parametrized decorators
5. Tag with hw_classification: Add hw_classification = HardwareClassification.GENERIC as the first class attribute. Import HardwareClassification from torch.testing._internal.common_utils (merge alphabetically into the existing common_utils import block). If the class uses instantiate_device_type_tests(only_for="cpu") for @ops, use HardwareClassification.CPU instead.

Strategy: Device-Agnostic

Tests that use a device parameter but only need generic accelerator APIs. This is the highest-impact refactoring — it unlocks tests for all accelerators at once.

Canonical Before/After

Before (false-CUDA):

from torch.testing._internal.common_cuda import TEST_CUDA

class TestFoo(TestCase):
    @unittest.skipIf(not TEST_CUDA, "no CUDA")
    def test_softmax_cuda(self):
        t = torch.randn(3, 3, device="cuda")
        result = t.softmax(0)
        self.assertEqual(result.sum(0), torch.ones(3, device="cuda"))

    @onlyCUDA
    @skipXPU  # XPU doesn't support this op yet
    def test_matmul_cuda(self, device):
        a = torch.randn(3, 3, device=device)
        b = torch.randn(3, 3, device=device)
        self.assertEqual(a @ b, torch.matmul(a, b))

After (device-agnostic):

from torch.testing._internal.common_device_type import (
    instantiate_device_type_tests, onlyAccelerator,
)
from torch.testing._internal.common_utils import HardwareClassification

class TestFooDevice(TestCase):
    hw_classification = HardwareClassification.ACCELERATOR

    @onlyAccelerator
    def test_softmax(self, device):
        t = torch.randn(3, 3, device=device)
        result = t.softmax(0)
        self.assertEqual(result.sum(0), torch.ones(3, device=device))

    @onlyAccelerator
    @skipXPU  # Still here — known gap
    def test_matmul(self, device):
        a = torch.randn(3, 3, device=device)
        b = torch.randn(3, 3, device=device)
        self.assertEqual(a @ b, torch.matmul(a, b))

instantiate_device_type_tests(TestFooDevice, globals())

Steps

1. Scrutinize every CUDA reference. Ask: "CUDA as device or CUDA as feature?" Most are the former → device-agnostic.
2. Create the device-agnostic class inheriting from TestCase. Decide whether to rename (see "Renaming Decision" above). If renaming, use TestFooDevice; otherwise keep the original name.
3. Add device parameter as first arg after self on each test method.
4. Replace hardcoded device strings: "cuda" → device param, .cuda() → .to(device).
5. Enlarge whitelist, keep blacklist: @onlyCUDA → @onlyAccelerator, @unittest.skipIf(not TEST_CUDA, ...) → @onlyAccelerator. Keep @skipXPU, @skipCUDAIf, @skipMPS, @skipMeta as-is; remove @onlyNativeDeviceTypes/@onlyNativeDeviceTypesAnd (redundant).
6. Replace device-specific APIs: torch.cuda.is_available() → torch.accelerator.is_available(), Category A APIs → torch.accelerator.* equivalents (see catalog).
7. Register: instantiate_device_type_tests(<ClassName>, globals()) at module level.
8. Tag with hw_classification: Add hw_classification = HardwareClassification.ACCELERATOR as the first class attribute. Import HardwareClassification from torch.testing._internal.common_utils (merge alphabetically into the existing common_utils import block).
9. Remove stale imports: TEST_CUDA, TEST_MPS only if no longer referenced.

Key Rules

• @onlyAccelerator is a method decorator, NOT a class decorator. Applied to a class, it replaces the class with a function and instantiate_device_type_tests fails.
• Use device-type-aware skips in device-agnostic classes: skipXPUIf(True, msg) / skipCUDAIf(condition, msg) from common_device_type (not common_utils) — these check self.device_type and only skip the specific device variant.
• Category A APIs (empty_cache, synchronize, CUDAGraph, memory_*) have torch.accelerator.* equivalents — they do NOT make a test CUDA-specific.
• Category B APIs (Stream, Event) are general concepts on all backends — they do NOT make a test CUDA-specific.

Strategy: Device-Specific

Tests requiring a particular accelerator's unique (Category C) features.

Device-specific classes use instantiate_device_type_tests(only_for="<device>"). Every test method takes a device parameter. Do NOT use a plain TestCase with a setUp guard — the test linter rejects it. Naming: keep the original class name — instantiate_device_type_tests appends the device name to generate the variant (e.g. TestFoo → TestFooCUDA). Do NOT pre-suffix the name with the device (TestFooOnCUDA + only_for="cuda" → TestFooOnCUDACUDA).

from torch.testing._internal.common_device_type import instantiate_device_type_tests
from torch.testing._internal.common_utils import HardwareClassification

class TestFoo(TestCase):
    hw_classification = HardwareClassification.CUDA

    def test_cuda_stream(self, device):
        s = torch.cuda.Stream()
        ...

instantiate_device_type_tests(TestFoo, globals(),

Because device-specific classes use instantiate_device_type_tests, @dtypes/@dtypesIfCUDA/@dtypesIfCPU/@parametrize decorators resolve correctly (they receive the device-type context from instantiation).

Steps:

1. Confirm the test genuinely uses Category C APIs.
2. Extract into the device-specific class. Decide whether to rename (see "Renaming Decision" above). Prefer the original name — hw_classification is the discriminator.
3. Add a device parameter as first arg after self on each test method. Keep Category C API calls (torch.cuda.*, etc.) as-is.
4. Register: instantiate_device_type_tests(<ClassName>, globals(),> at module level.
5. Tag with hw_classification: Add hw_classification = HardwareClassification.CUDA (or MPS, XPU per device) as the first class attribute. Import HardwareClassification from torch.testing._internal.common_utils (merge alphabetically into the existing common_utils import block).

python -c "
from torch.testing._internal.common_methods_invocations import op_db
from torch.testing._internal.opinfo.core import DecorateInfo
old = {'TestOldName1', 'TestOldName2'}
for op in op_db:
    for d in op.decorators:
        if isinstance(d, DecorateInfo) and d.cls_name in old:
            print(f'{op.name}: cls_name={d.cls_name}, test_name={d.test_name}')
"

# Find stale entries after renaming TestFoo -> TestFooDevice
ls test/dynamo_skips/TestFoo.* 2>/dev/null

# Find stale entries after renaming TestFoo -> TestFooDevice
ls test/dynamo_expected_failures/TestFoo.* 2>/dev/null