fix: show config errors once at session start instead of per-test (#55)

* docs: update pre-commit section with args example, fix stale v1.3.0 refs

- pre-commit section: add args example for Alembic and Django, note on
  pre-commit autoupdate, update rev from v1.3.0 to v1.2.0
- Remove (v1.3.0) version labels from section headers for unreleased features
- Update 'What's new' section to reflect v1.2.0 accurately

Closes #35

* fix: improve mrt init UX — fix db_url quoting bug, clearer prompts and next steps

Three issues fixed:

1. db_url quoting bug: when a user typed a literal URL (e.g. sqlite:///test.db),
   it was written as db_url=sqlite:///test.db without quotes — invalid Python.
   Now correctly written as db_url="sqlite:///test.db".

2. Confusing default prompt: the old default was the raw Python expression
   os.environ.get("TEST_DATABASE_URL", "sqlite:///test.db") which is unclear
   for first-time users. Default is now simply sqlite:///test.db with a tip
   explaining the env var pattern for CI.

3. Weak next steps: the completion message now shows numbered steps, static
   analysis command, and a docs link — so users know exactly what to do next.

Also removes unnecessary 'import os' from generated conftest when a literal
URL is used (os is only imported when the url expr references os.environ).

* fix: show config errors once at session start instead of per-test

Before this change, a missing alembic.ini produced the same error
message for every collected test (typically 7 times), each with a
double traceback due to pytest.fail() being called inside an except
block.

Changes:
- Add pytest_sessionstart hook that validates MRTConfig once and calls
  pytest.exit() on fatal config errors -- one clear message, no tests run
- Break exception chain in mrt fixture (capture error string before
  calling pytest.fail) to eliminate "During handling of the above
  exception" noise
- Simplify MRTConfigError message in MRTFixture.__init__: Django hint
  is now only shown via pytest_sessionstart, not duplicated
- Update test assertion to match revised error message text

Author: croc100

pytest_mrt/plugin.py

@@ -83,13 +83,9 @@ def __init__(self, config: MRTConfig):
 
             if not _Path(config.alembic_ini).exists():
                 raise MRTConfigError(
-                    f"\n\n  alembic.ini not found: '{config.alembic_ini}'\n\n"
-                    "  If you are using Django migrations (not Alembic), use:\n\n"
-                    "    config._mrt_config = MRTConfig(\n"
-                    "        db_url=os.environ['TEST_DATABASE_URL'],\n"
-                    "        django_settings='myproject.settings_test',\n"
-                    "    )\n\n"
-                    "  See: https://croc100.github.io/pytest-mrt/quickstart/#django"
+                    f"alembic.ini not found: '{config.alembic_ini}'\n\n"
+                    "Check the path and update MRTConfig(alembic_ini=...) in your conftest.py.\n"
+                    "See: https://croc100.github.io/pytest-mrt/quickstart/"
                 )
 
             self._runner = MigrationRunner(config.alembic_ini, config.db_url)
@@ -301,6 +297,39 @@ def pytest_configure(config: pytest.Config) -> None:
     config.addinivalue_line("markers", "mrt: migration rollback test")
 
 
+def pytest_sessionstart(session: pytest.Session) -> None:
+    """Validate MRTConfig once at session start.
+
+    Catches obvious setup errors (missing alembic.ini, etc.) before any test
+    runs, so the user sees one clear error instead of the same message repeated
+    for every collected test.
+    """
+    cfg: MRTConfig | None = getattr(session.config, "_mrt_config", None)
+    if cfg is None:
+        return
+
+    cfg = _auto_detect_django(cfg)
+
+    # Django mode — no alembic.ini needed
+    if cfg.django_settings is not None:
+        return
+
+    from pathlib import Path
+
+    if not Path(cfg.alembic_ini).exists():
+        msg = (
+            f"alembic.ini not found: '{cfg.alembic_ini}'\n\n"
+            "Check the path and update MRTConfig(alembic_ini=...) in your conftest.py.\n\n"
+            "If you are using Django migrations (not Alembic), set django_settings instead:\n\n"
+            "    config._mrt_config = MRTConfig(\n"
+            "        db_url=os.environ['TEST_DATABASE_URL'],\n"
+            "        django_settings='myproject.settings_test',\n"
+            "    )\n\n"
+            "See: https://croc100.github.io/pytest-mrt/quickstart/"
+        )
+        pytest.exit(msg, returncode=4)
+
+
 def pytest_collection_modifyitems(
     session: pytest.Session,
     config: pytest.Config,
@@ -336,9 +365,15 @@ def pytest_collection_modifyitems(
 @pytest.fixture
 def mrt(request: pytest.FixtureRequest) -> Iterator[MRTFixture]:
     cfg: MRTConfig = getattr(request.config, "_mrt_config", None) or MRTConfig()
+    # Capture error outside the except block to avoid "During handling of the
+    # above exception, another exception occurred" in the traceback output.
+    config_error: str | None = None
     try:
         fixture = MRTFixture(cfg)
     except MRTConfigError as e:
-        pytest.fail(str(e), pytrace=False)
+        config_error = str(e)
+    if config_error is not None:
+        pytest.fail(config_error, pytrace=False)
+        return  # unreachable; keeps type checkers happy
     yield fixture
     fixture.reset()

tests/test_plugin.py

@@ -665,13 +665,13 @@ def test_auto_detect_django_no_switch_when_explicit_django_settings(tmp_path, mo
 
 
 def test_mrt_fixture_raises_on_missing_alembic_ini(tmp_path, monkeypatch):
-    """MRTFixture raises MRTConfigError with a Django hint when alembic.ini is missing."""
+    """MRTFixture raises MRTConfigError when alembic.ini is missing."""
     from pytest_mrt.exceptions import MRTConfigError
 
     monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
 
     cfg = MRTConfig(alembic_ini=str(tmp_path / "nonexistent.ini"), db_url="sqlite:///test.db")
-    with pytest.raises(MRTConfigError, match="django_settings"):
+    with pytest.raises(MRTConfigError, match="alembic.ini not found"):
         MRTFixture(cfg)