A loose federation of distributed, typed datasets
1# Expected Test Warnings
2
3This document explains the expected warnings that are suppressed in the test suite using `@pytest.mark.filterwarnings` decorators.
4
5## Design Philosophy
6
7Per the project's testing conventions (see `CLAUDE.md`), warning suppression is kept **local to individual tests** rather than using global suppression in `conftest.py`. This approach:
8
91. Documents which specific tests have known warning behaviors
102. Makes it easier to track when warnings appear in unexpected places
113. Avoids masking genuine warnings from new code
12
13## Warning Categories
14
15### 1. s3fs/moto Async Incompatibility
16
17**Warnings:**
18```python
19@pytest.mark.filterwarnings("ignore::pytest.PytestUnraisableExceptionWarning")
20@pytest.mark.filterwarnings("ignore:coroutine.*was never awaited:RuntimeWarning")
21```
22
23**Cause:** The `s3fs` library (used for S3 filesystem access) has async internals that don't fully clean up when used with `moto` (AWS mocking library) in a synchronous test context. When the test tears down, some async coroutines haven't been awaited, triggering these warnings.
24
25**Affected tests:** Any test using the `mock_s3` fixture that interacts with `S3DataStore` or `S3FileSystem`.
26
27**Impact:** None on test correctness. These are cleanup warnings that occur after the test has completed successfully.
28
29**Resolution status:** This is a known interaction between s3fs and moto. A proper fix would require upstream changes to one or both libraries. The warnings are harmless and are expected behavior when using these libraries together.
30
31### 2. Deprecated Repo Class
32
33**Warning:**
34```python
35@pytest.mark.filterwarnings("ignore:Repo is deprecated:DeprecationWarning")
36```
37
38**Cause:** The `Repo` class in `atdata.local` is deprecated in favor of `LocalIndex`. Tests that verify backward compatibility or test the deprecated class directly will trigger this warning.
39
40**Affected tests:** Tests in `TestRepoWorkflow`, `TestRepoDeprecation`, and any test explicitly using the `Repo` class.
41
42**Impact:** None on test correctness. The deprecation warning is intentional to guide users toward `LocalIndex`.
43
44**Resolution status:** These warnings will be removed when the `Repo` class is removed in a future major version. Until then, tests maintain backward compatibility verification.
45
46## Adding New Warning Suppressions
47
48When adding new `filterwarnings` markers:
49
501. **Verify the warning is expected** - Understand why the warning occurs and confirm it doesn't indicate a real problem
512. **Use specific patterns** - Target only the exact warning, not broad categories
523. **Document here** - Add an entry explaining the warning
534. **Keep it local** - Apply to individual tests, not globally
54
55Example:
56```python
57@pytest.mark.filterwarnings("ignore:specific warning pattern:WarningType")
58def test_something():
59 ...
60```
61
62## Files with Warning Suppressions
63
64- `tests/test_local.py` - s3fs/moto async warnings, Repo deprecation
65- `tests/test_integration_local.py` - s3fs/moto async warnings, Repo deprecation
66
67## Verifying Warnings Are Still Expected
68
69Periodically check if upstream fixes have resolved these issues:
70
71```bash
72# Run tests without suppressions to see all warnings
73uv run pytest tests/test_local.py -W default 2>&1 | grep -i warning
74```