pytest-tzcheck 0.1.0__py3-none-any.whl

pytest_tzcheck/__init__.py

@@ -0,0 +1 @@
+"""Run tests in several timezones and report the ones whose outcome changes."""

pytest_tzcheck/plugin.py

@@ -0,0 +1,164 @@
+"""pytest plugin: run each test in several timezones, report tests whose outcome changes."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+import pytest
+
+from pytest_tzcheck import zones
+
+FIXTURE = "tzcheck_zone"
+PROP_ZONE = "tzcheck_zone"
+PROP_BASE = "tzcheck_base_nodeid"
+
+# Worst outcome wins when a test has several phases (setup, call, teardown).
+_RANK = {"passed": 0, "xfailed": 1, "xpassed": 1, "skipped": 2, "failed": 3, "error": 4}
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("tzcheck", "timezone dependence")
+    group.addoption(
+        "--tzcheck",
+        action="store_true",
+        default=None,
+        help="run each test in several timezones and report tests whose outcome depends on it.",
+    )
+    group.addoption(
+        "--tzcheck-zones",
+        metavar="ZONES",
+        help=f"comma-separated IANA zones or presets ({', '.join(zones.PRESETS)}). "
+        f"'{zones.LOCAL}' is the current zone. Default: ci ({','.join(zones.PRESETS['ci'])}).",
+    )
+    parser.addini("tzcheck", "enable --tzcheck by default", type="bool", default=False)
+    parser.addini("tzcheck_zones", "zones for --tzcheck (see --tzcheck-zones)", default="ci")
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line(
+        "markers",
+        "no_tzcheck: run this test only in the local timezone, even with --tzcheck.",
+    )
+    enabled = config.getoption("tzcheck")
+    if enabled is None:
+        enabled = config.getini("tzcheck")
+    if not enabled:
+        return
+    if not zones.supported():
+        raise pytest.UsageError("--tzcheck needs time.tzset(), which this platform does not have.")
+    names = zones.parse(config.getoption("tzcheck_zones") or config.getini("tzcheck_zones"))
+    for name in names:
+        try:
+            zones.validate(name)
+        except ValueError as exc:
+            raise pytest.UsageError(f"--tzcheck-zones: {exc}") from None
+    config.pluginmanager.register(TzCheck(zones.dedupe(names)), "tzcheck-session")
+
+
+@pytest.fixture
+def tzcheck_zone(request: pytest.FixtureRequest) -> str:
+    """The timezone this test runs in: an IANA name, or "local" for the untouched environment."""
+    return getattr(request, "param", zones.LOCAL)
+
+
+def _zone_of(item: pytest.Item) -> str | None:
+    callspec = getattr(item, "callspec", None)
+    return callspec.params.get(FIXTURE) if callspec else None
+
+
+def _base_nodeid(nodeid: str, zone: str) -> str:
+    suffix = f"tz={zone}]"
+    if not nodeid.endswith(suffix):
+        return nodeid
+    head = nodeid[: -len(suffix)]
+    return head[:-1] if head.endswith("[") else head[:-1] + "]"
+
+
+def _outcome(report: pytest.TestReport) -> str | None:
+    if hasattr(report, "wasxfail"):
+        return "xfailed" if report.skipped else "xpassed"
+    if report.failed:
+        return "failed" if report.when == "call" else "error"
+    if report.skipped:
+        return "skipped"
+    return "passed" if report.when == "call" else None
+
+
+class TzCheck:
+    def __init__(self, names: list[str]) -> None:
+        self.names = names
+        self.local = zones.local_name()
+        self.results: dict[str, dict[str, str]] = defaultdict(dict)
+
+    def label(self, zone: str) -> str:
+        return f"{zone} ({self.local})" if zone == zones.LOCAL else zone
+
+    def pytest_report_header(self) -> str:
+        if len(self.names) < 2:
+            return (
+                f"tzcheck: only one distinct zone ({self.label(self.names[0])}), nothing to compare"
+            )
+        return "tzcheck: " + ", ".join(self.label(z) for z in self.names)
+
+    @pytest.hookimpl(trylast=True)
+    def pytest_generate_tests(self, metafunc: pytest.Metafunc) -> None:
+        if len(self.names) < 2 or metafunc.definition.get_closest_marker("no_tzcheck"):
+            return
+        if FIXTURE not in metafunc.fixturenames:
+            metafunc.fixturenames.append(FIXTURE)
+        metafunc.parametrize(
+            FIXTURE, self.names, indirect=True, ids=[f"tz={z}" for z in self.names]
+        )
+
+    @pytest.hookimpl(hookwrapper=True)
+    def pytest_runtest_protocol(self, item: pytest.Item, nextitem: pytest.Item | None):
+        zone = _zone_of(item)
+        if zone is None:
+            yield
+            return
+        item.user_properties.append((PROP_ZONE, zone))
+        item.user_properties.append((PROP_BASE, _base_nodeid(item.nodeid, zone)))
+        with zones.set_local_zone(zone):
+            yield
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        props = dict(report.user_properties)
+        zone, base = props.get(PROP_ZONE), props.get(PROP_BASE)
+        outcome = _outcome(report)
+        if zone is None or base is None or outcome is None:
+            return
+        current = self.results[base].get(zone)
+        if current is None or _RANK[outcome] > _RANK[current]:
+            self.results[base][zone] = outcome
+
+    def dependent(self) -> dict[str, dict[str, str]]:
+        return {
+            base: by_zone
+            for base, by_zone in self.results.items()
+            if len(set(by_zone.values())) > 1
+        }
+
+    def pytest_terminal_summary(self, terminalreporter) -> None:
+        if not self.results:
+            return
+        dependent = self.dependent()
+        if not dependent:
+            terminalreporter.write_line(
+                f"tzcheck: no timezone-dependent tests "
+                f"({len(self.results)} tests x {len(self.names)} zones)"
+            )
+            return
+        terminalreporter.section("timezone-dependent tests", red=True, bold=True)
+        for base in sorted(dependent):
+            by_outcome: dict[str, list[str]] = defaultdict(list)
+            for zone in self.names:
+                if zone in dependent[base]:
+                    by_outcome[dependent[base][zone]].append(self.label(zone))
+            parts = "   ".join(
+                f"{outcome}: {', '.join(labels)}" for outcome, labels in by_outcome.items()
+            )
+            terminalreporter.write_line(f"{base}   {parts}")
+        terminalreporter.write_line(
+            f"{len(dependent)} of {len(self.results)} tests changed outcome with the timezone",
+            red=True,
+        )

pytest_tzcheck/zones.py

@@ -0,0 +1,118 @@
+"""Timezone presets, validation, and switching the process's local timezone."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import time
+from collections.abc import Iterator
+from datetime import datetime, timedelta, timezone
+from zoneinfo import TZPATH, ZoneInfo, ZoneInfoNotFoundError
+
+LOCAL = "local"
+
+PRESETS: dict[str, list[str]] = {
+    "ci": [LOCAL, "UTC"],
+    "wide": [
+        LOCAL,
+        "UTC",
+        "Pacific/Kiritimati",  # UTC+14: the local date differs from UTC's most of the day
+        "America/St_Johns",  # half-hour offset, northern DST
+        "Australia/Lord_Howe",  # half-hour DST shift, southern hemisphere
+    ],
+}
+
+
+def supported() -> bool:
+    return hasattr(time, "tzset")
+
+
+def parse(spec: str) -> list[str]:
+    """Expand a comma-separated list of zone names and presets, keeping order."""
+    names: list[str] = []
+    for part in spec.split(","):
+        part = part.strip()
+        for name in PRESETS.get(part, [part] if part else []):
+            if name not in names:
+                names.append(name)
+    return names
+
+
+def validate(name: str) -> None:
+    """Raise ValueError unless the C library can load `name` from the system tz database.
+
+    libc silently falls back to UTC for a TZ it cannot find, so a typo would
+    look like a real run in UTC.
+    """
+    if name == LOCAL:
+        return
+    try:
+        ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError) as exc:
+        raise ValueError(f"unknown timezone {name!r}") from exc
+    if not any(os.path.isfile(os.path.join(path, name)) for path in TZPATH):
+        raise ValueError(
+            f"timezone {name!r} is not in the system tz database ({', '.join(TZPATH)})"
+        )
+
+
+def _apply() -> None:
+    time.tzset()
+    tzlocal = sys.modules.get("tzlocal")
+    reload_localzone = getattr(tzlocal, "reload_localzone", None)
+    if reload_localzone is not None:
+        with contextlib.suppress(Exception):
+            reload_localzone()
+
+
+@contextlib.contextmanager
+def set_local_zone(name: str) -> Iterator[None]:
+    """Make `name` the process's local timezone (and its subprocesses') for the block."""
+    if name == LOCAL:
+        yield
+        return
+    previous = os.environ.get("TZ")
+    os.environ["TZ"] = name
+    _apply()
+    try:
+        yield
+    finally:
+        if previous is None:
+            os.environ.pop("TZ", None)
+        else:
+            os.environ["TZ"] = previous
+        _apply()
+
+
+def signature(name: str) -> tuple[int, ...]:
+    """UTC offset at noon UTC on every day of the current year."""
+    with set_local_zone(name):
+        start = datetime(datetime.now(timezone.utc).year, 1, 1, 12, tzinfo=timezone.utc)
+        return tuple(
+            time.localtime((start + timedelta(days=d)).timestamp()).tm_gmtoff for d in range(366)
+        )
+
+
+def dedupe(names: list[str]) -> list[str]:
+    """Drop zones whose offsets match an earlier zone's, e.g. 'UTC' when local is UTC."""
+    seen: set[tuple[int, ...]] = set()
+    kept = []
+    for name in names:
+        sig = signature(name)
+        if sig not in seen:
+            seen.add(sig)
+            kept.append(name)
+    return kept
+
+
+def local_name() -> str:
+    """Best-effort IANA name of the current local zone, for display."""
+    tz = os.environ.get("TZ")
+    if tz:
+        return tz.lstrip(":")
+    with contextlib.suppress(OSError):
+        target = os.path.realpath("/etc/localtime")
+        if "zoneinfo/" in target:
+            return target.split("zoneinfo/", 1)[1]
+    return time.tzname[0]

pytest_tzcheck-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+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

pytest_tzcheck-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pytest_tzcheck/__init__.py,sha256=TLUuyJx0N4tQFG3JAN50i9qkcgwP0IAu2bcDn-r-l8w,80
+pytest_tzcheck/plugin.py,sha256=zRxBOrX3sy-5iIpGyNalKPlhMaAR0UPV5MkZTpKc1Jw,6207
+pytest_tzcheck/zones.py,sha256=WwneTnJ__nVWiVzKoR0SN6Z1nR7AHeVnhIDlYhbLQz0,3534
+pytest_tzcheck-0.1.0.dist-info/METADATA,sha256=PtOPHQF-mKEbgiFJOEDzLp5nhWWYAuWWCjj5oFOY_F8,7594
+pytest_tzcheck-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pytest_tzcheck-0.1.0.dist-info/entry_points.txt,sha256=NBsaePkT6Qv02MzXfPDTcGdBw7nvMa8AtKfH4a3sC9Q,43
+pytest_tzcheck-0.1.0.dist-info/licenses/LICENSE,sha256=pPpLggfVf4TFbMr-FLE9gLslHnElioeve81adhHgzNI,1067
+pytest_tzcheck-0.1.0.dist-info/RECORD,,

pytest_tzcheck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_tzcheck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+tzcheck = pytest_tzcheck.plugin

pytest_tzcheck-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariel Even
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.