Metadata-Version: 2.5
Name: pytest-tzcheck
Version: 0.1.0
Summary: Run your tests in the timezone CI uses, and find the ones that only pass in yours.
Project-URL: Repository, https://github.com/taltal-beep/pytest-tzcheck
Author-email: Ariel Even <ttlgptinc@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: flaky,pytest,testing,timezone,tz
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Requires-Dist: pytest>=7
Description-Content-Type: text/markdown

# pytest-tzcheck

Run your tests in the timezone CI uses, and find the ones that only pass in yours.

"Passes on my machine, fails in CI" often comes down to the local timezone: your laptop is in Asia/Jerusalem, the CI runner is in UTC. `pytest --tzcheck` runs every test in both zones and tells you which ones change outcome, before you push.

```
$ pytest --tzcheck tests/server/schemas/test_schedules.py
tzcheck: local (Asia/Jerusalem), UTC
...
=========================== timezone-dependent tests ===========================
tests/server/schemas/test_schedules.py::TestRRuleSchedule::test_rrule_schedule_preserves_and_localizes_rdates   passed: local (Asia/Jerusalem)   failed: UTC
```

## Install

```bash
pip install pytest-tzcheck
```

Python 3.9+, pytest 7+, Linux or macOS (it needs `time.tzset()`, which Windows does not have).

## Usage

```bash
pytest --tzcheck                                    # local zone + UTC (the "ci" preset)
pytest --tzcheck --tzcheck-zones=wide               # local, UTC, +14h, half-hour offsets, southern DST
pytest --tzcheck --tzcheck-zones=UTC,America/New_York
pytest --tzcheck -k "tz=UTC"                        # only the UTC runs
```

Or turn it on in config:

```ini
[pytest]
tzcheck = true
tzcheck_zones = ci
```

| Zone list | Zones |
|---|---|
| `ci` (default) | `local`, `UTC` |
| `wide` | `local`, `UTC`, `Pacific/Kiritimati` (UTC+14, the local date is not UTC's most of the day), `America/St_Johns` (half-hour offset), `Australia/Lord_Howe` (half-hour DST shift, southern hemisphere) |

`local` is the environment as you started pytest. Presets and IANA names can be mixed. Zones with the same UTC offsets all year are merged, so on a UTC CI runner `--tzcheck` does not double the run.

Opt a test out with `@pytest.mark.no_tzcheck`. A test can ask which zone it runs in through the `tzcheck_zone` fixture.

A failure in any zone fails the run, so `--tzcheck` works as a CI gate as well as a local check.

## How it works

1. Each test is parametrized over the zones (`test_x[tz=local]`, `test_x[tz=UTC]`), so the runs are ordinary pytest items: `-k`, `--lf`, JUnit XML and pytest-xdist all work.
2. Around each run (setup, call and teardown) the plugin sets `TZ`, calls `time.tzset()`, and restores both afterwards. Subprocesses started by the test inherit the zone. If `tzlocal` is imported, its cache is reloaded.
3. The outcome of each run is recorded, and the summary lists every test whose outcome differs between zones. A test that fails everywhere is not listed: that is a bug, but not a timezone bug.

## Case study: a prefect PR

This plugin started from a real bug. While fixing RDATE/EXDATE handling in prefect's `RRuleSchedule` ([PrefectHQ/prefect#23436](https://github.com/PrefectHQ/prefect/pull/23436)), the new regression tests passed locally (Asia/Jerusalem) and failed in CI (UTC).

The cause: dateutil parses a timestamp ending in `Z` as `tzutc()`, unless the machine's local zone is UTC, in which case it returns `tzlocal()`. The fix checked `isinstance(dt.tzinfo, tzutc)`, which is true in Jerusalem and false in UTC. Nothing in that code path calls a local-time function; dateutil just compares against `time.tzname`.

Prefect's schedule tests on the commit that failed CI (`bb4f72475`):

```
$ pytest tests/client/schemas/test_schedules.py tests/server/schemas/test_schedules.py
155 passed, 6 skipped, 2 xfailed

$ pytest --tzcheck tests/client/schemas/test_schedules.py tests/server/schemas/test_schedules.py
=========================== timezone-dependent tests ===========================
tests/client/schemas/test_schedules.py::TestRRuleScheduleFromRRule::test_rruleset_keeps_rdate_and_exdate_instants_in_another_timezone   passed: local (Asia/Jerusalem)   failed: UTC
tests/server/schemas/test_schedules.py::TestRRuleSchedule::test_rrule_schedule_preserves_and_localizes_exdates   passed: local (Asia/Jerusalem)   failed: UTC
tests/server/schemas/test_schedules.py::TestRRuleSchedule::test_rrule_schedule_preserves_and_localizes_rdates   passed: local (Asia/Jerusalem)   failed: UTC
tests/server/schemas/test_schedules.py::TestRRuleSchedule::test_serialization_preserves_rdate_and_exdate_in_another_timezone   passed: local (Asia/Jerusalem)   failed: UTC
tests/server/schemas/test_schedules.py::TestRRuleSchedule::test_serialization_preserves_rrules_rdates_exrules_exdates   passed: local (Asia/Jerusalem)   failed: UTC
5 of 163 tests changed outcome with the timezone
5 failed, 305 passed, 12 skipped, 4 xfailed
```

On the fixed commit (`9e24d058d`, which checks the UTC offset instead of the tzinfo type):

```
$ pytest --tzcheck tests/client/schemas/test_schedules.py tests/server/schemas/test_schedules.py
tzcheck: no timezone-dependent tests (163 tests x 2 zones)
310 passed, 12 skipped, 4 xfailed
```

## Why run every test, rather than detect the risky ones?

The cheaper design is to trace calls to local-time APIs (`time.localtime`, naive `datetime.now()`, `astimezone()` without arguments) and rerun only the tests that make them. It would have missed the bug above: in Jerusalem, dateutil only *reads* `time.tzname`, an attribute, so no call is made. Running each test in each zone and comparing outcomes has no false positives and no blind spots, at the cost of one extra run per zone. Linters such as ruff's `DTZ` rules cover the static side.

## Limitations

- Fixtures with module, class or session scope are created once, in the zone of the first test that uses them. Values computed at import time (a module-level `tz.tzlocal()`, a cached `get_localzone()` result) also stay in the first zone.
- The zone is per process: threads running during the test see it too.
- POSIX only.
- libc silently treats an unknown `TZ` as UTC, so the plugin refuses zone names that are not in the system tz database.

## Roadmap

- `--tzcheck-mode=probe`: trace local-time calls with `sys.monitoring` (Python 3.12+) and rerun only those tests in the extra zones, as a fast pre-filter for large suites, with the blind spot above documented.
- Run each zone at a few fixed instants (around midnight UTC, DST transitions), since many timezone bugs only show up at certain hours.
- A JSON report for CI annotations.

## Development

```bash
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
```

To try it on another project without installing it: `PYTHONPATH=path/to/pytest-tzcheck/src pytest -p pytest_tzcheck.plugin --tzcheck`.

## Releasing

Pushing a `v*` tag runs `.github/workflows/release.yml`: it checks the tag matches the version in `pyproject.toml`, runs lint and tests, builds, and publishes to PyPI through trusted publishing (no API token).

```bash
uv version --bump patch        # or minor / major
git commit -am "Release $(uv version --short)"
git tag "v$(uv version --short)"
git push origin main --tags
```

## License

MIT
