Add test_mode_samples() accessor for PYAUTO_TEST_MODE_SAMPLES

Number of fake samples the test-mode sampler bypass writes (default 4 =
historical behaviour; values below 4 raise). Consumed by PyAutoFit's
_build_fake_samples to write size-realistic samples.csv outputs
(PyAutoFit#1379; design locked on PyAutoFit#1378).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

autoconf/test_mode.py

@@ -21,6 +21,30 @@ def is_test_mode():
     return test_mode_level() > 0
 
 
+def test_mode_samples():
+    """
+    Return the number of fake samples the test-mode sampler bypass writes.
+
+    Controlled by ``PYAUTO_TEST_MODE_SAMPLES`` (default 4, the historical
+    bypass sample count — unset behaviour is unchanged). Larger values make
+    a ``PYAUTO_TEST_MODE=2``/``3`` bypass run write a ``samples.csv`` whose
+    row count and byte size are representative of a production sampler run
+    (N ~ 10k-100k), so resume/load timings measured against the output are
+    honest while the fit itself completes in seconds.
+
+    Values below 4 raise: 4 is the minimum that preserves the bypass
+    sample structure downstream code is tested against.
+    """
+    samples = int(os.environ.get("PYAUTO_TEST_MODE_SAMPLES", "4"))
+    if samples < 4:
+        raise ValueError(
+            f"PYAUTO_TEST_MODE_SAMPLES must be >= 4 (got {samples}) — 4 is "
+            f"the minimum that preserves the test-mode bypass sample "
+            f"structure."
+        )
+    return samples
+
+
 def skip_fit_output():
     """
     Return True if fit I/O should be skipped.

test_autoconf/test_test_mode.py

@@ -11,6 +11,7 @@
 from autoconf.test_mode import (
     is_test_mode,
     test_mode_level,
+    test_mode_samples,
     with_test_mode_segment,
 )
 
@@ -54,3 +55,27 @@ def test_with_test_mode_segment__chains_with_pathlib_concat():
     os.environ["PYAUTO_TEST_MODE"] = "2"
     composed = with_test_mode_segment(Path("output")) / "results_folder"
     assert composed == Path("output") / "test_mode" / "results_folder"
+
+
+class TestTestModeSamples:
+    @pytest.fixture(autouse=True)
+    def _restore_samples_env(self):
+        saved = os.environ.get("PYAUTO_TEST_MODE_SAMPLES")
+        yield
+        if saved is None:
+            os.environ.pop("PYAUTO_TEST_MODE_SAMPLES", None)
+        else:
+            os.environ["PYAUTO_TEST_MODE_SAMPLES"] = saved
+
+    def test__env_unset_returns_historical_default_of_four(self):
+        os.environ.pop("PYAUTO_TEST_MODE_SAMPLES", None)
+        assert test_mode_samples() == 4
+
+    def test__env_set_returns_value(self):
+        os.environ["PYAUTO_TEST_MODE_SAMPLES"] = "50000"
+        assert test_mode_samples() == 50000
+
+    def test__values_below_four_raise(self):
+        os.environ["PYAUTO_TEST_MODE_SAMPLES"] = "3"
+        with pytest.raises(ValueError):
+            test_mode_samples()