|
| 1 | +# Testing Guidelines for xarray |
| 2 | + |
| 3 | +## Handling Optional Dependencies |
| 4 | + |
| 5 | +xarray has many optional dependencies that may not be available in all testing environments. Always use the standard decorators and patterns when writing tests that require specific dependencies. |
| 6 | + |
| 7 | +### Standard Decorators |
| 8 | + |
| 9 | +**ALWAYS use decorators** like `@requires_dask`, `@requires_cftime`, etc. instead of conditional `if` statements. |
| 10 | + |
| 11 | +All available decorators are defined in `xarray/tests/__init__.py` (look for `requires_*` decorators). |
| 12 | + |
| 13 | +### DO NOT use conditional imports or skipif |
| 14 | + |
| 15 | +❌ **WRONG - Do not do this:** |
| 16 | + |
| 17 | +```python |
| 18 | +def test_mean_with_cftime(): |
| 19 | + if has_dask: # WRONG! |
| 20 | + ds = ds.chunk({}) |
| 21 | + result = ds.mean() |
| 22 | +``` |
| 23 | + |
| 24 | +❌ **ALSO WRONG - Avoid pytest.mark.skipif in parametrize:** |
| 25 | + |
| 26 | +```python |
| 27 | +@pytest.mark.parametrize( |
| 28 | + "chunk", |
| 29 | + [ |
| 30 | + pytest.param( |
| 31 | + True, marks=pytest.mark.skipif(not has_dask, reason="requires dask") |
| 32 | + ), |
| 33 | + False, |
| 34 | + ], |
| 35 | +) |
| 36 | +def test_something(chunk): ... |
| 37 | +``` |
| 38 | + |
| 39 | +✅ **CORRECT - Do this instead:** |
| 40 | + |
| 41 | +```python |
| 42 | +def test_mean_with_cftime(): |
| 43 | + # Test without dask |
| 44 | + result = ds.mean() |
| 45 | + |
| 46 | + |
| 47 | +@requires_dask |
| 48 | +def test_mean_with_cftime_dask(): |
| 49 | + # Separate test for dask functionality |
| 50 | + ds = ds.chunk({}) |
| 51 | + result = ds.mean() |
| 52 | +``` |
| 53 | + |
| 54 | +✅ **OR for parametrized tests, split them:** |
| 55 | + |
| 56 | +```python |
| 57 | +def test_something_without_dask(): |
| 58 | + # Test the False case |
| 59 | + ... |
| 60 | + |
| 61 | + |
| 62 | +@requires_dask |
| 63 | +def test_something_with_dask(): |
| 64 | + # Test the True case with dask |
| 65 | + ... |
| 66 | +``` |
| 67 | + |
| 68 | +### Multiple dependencies |
| 69 | + |
| 70 | +When a test requires multiple optional dependencies: |
| 71 | + |
| 72 | +```python |
| 73 | +@requires_dask |
| 74 | +@requires_scipy |
| 75 | +def test_interpolation_with_dask(): ... |
| 76 | +``` |
| 77 | + |
| 78 | +### Importing optional dependencies in tests |
| 79 | + |
| 80 | +For imports within test functions, use `pytest.importorskip`: |
| 81 | + |
| 82 | +```python |
| 83 | +def test_cftime_functionality(): |
| 84 | + cftime = pytest.importorskip("cftime") |
| 85 | + # Now use cftime |
| 86 | +``` |
| 87 | + |
| 88 | +### Common patterns |
| 89 | + |
| 90 | +1. **Split tests by dependency** - Don't mix optional dependency code with base functionality: |
| 91 | + |
| 92 | + ```python |
| 93 | + def test_base_functionality(): |
| 94 | + # Core test without optional deps |
| 95 | + result = ds.mean() |
| 96 | + assert result is not None |
| 97 | + |
| 98 | + |
| 99 | + @requires_dask |
| 100 | + def test_dask_functionality(): |
| 101 | + # Dask-specific test |
| 102 | + ds_chunked = ds.chunk({}) |
| 103 | + result = ds_chunked.mean() |
| 104 | + assert result is not None |
| 105 | + ``` |
| 106 | + |
| 107 | +2. **Use fixtures for dependency-specific setup**: |
| 108 | + |
| 109 | + ```python |
| 110 | + @pytest.fixture |
| 111 | + def dask_array(): |
| 112 | + pytest.importorskip("dask.array") |
| 113 | + import dask.array as da |
| 114 | + |
| 115 | + return da.from_array([1, 2, 3], chunks=2) |
| 116 | + ``` |
| 117 | + |
| 118 | +3. **Check available implementations**: |
| 119 | + |
| 120 | + ```python |
| 121 | + from xarray.core.duck_array_ops import available_implementations |
| 122 | + |
| 123 | + |
| 124 | + @pytest.mark.parametrize("implementation", available_implementations()) |
| 125 | + def test_with_available_backends(implementation): ... |
| 126 | + ``` |
| 127 | + |
| 128 | +### Key Points |
| 129 | + |
| 130 | +- CI environments intentionally exclude certain dependencies (e.g., `all-but-dask`, `bare-minimum`) |
| 131 | +- A test failing in "all-but-dask" because it uses dask is a test bug, not a CI issue |
| 132 | +- Look at similar existing tests for patterns to follow |
![pre-commit-ci[bot]](https://avatars.githubusercontent.com/in/68672?v=4&size=40){kind=avatar}
0 commit comments