document random_seed

src/doc/en/developer/doctesting.rst

@@ -803,6 +803,57 @@ You can also pass in an explicit amount of time::
 Finally, you can disable any warnings about long tests with
 ``--warn-long 0``.
 
+Doctests start from a random seed::
+
+    [kliem@sage sage-9.2]$ sage -t src/sage/doctest/tests/random_seed.rst
+    Running doctests with ID 2020-06-23-23-22-59-49f37a55.
+    ...
+    Doctesting 1 file.
+    sage -t --warn-long 89.5 --random_seed=112986622569797306072457879734474628454 src/sage/doctest/tests/random_seed.rst
+    **********************************************************************
+    File "src/sage/doctest/tests/random_seed.rst", line 3, in sage.doctest.tests.random_seed
+    Failed example:
+        randint(5, 10)
+    Expected:
+        9
+    Got:
+        8
+    **********************************************************************
+    1 item had failures:
+       1 of   2 in sage.doctest.tests.random_seed
+        [1 test, 1 failure, 0.00 s]
+    ----------------------------------------------------------------------
+    sage -t --warn-long 89.5 --random_seed=112986622569797306072457879734474628454 src/sage/doctest/tests/random_seed.rst  # 1 doctest failed
+    ----------------------------------------------------------------------
+    Total time for all tests: 0.0 seconds
+        cpu time: 0.0 seconds
+        cumulative wall time: 0.0 seconds
+
+This seed can be set explicitly to reproduce possible failures::
+
+    [kliem@sage sage-9.2]$ sage -t --warn-long 89.5 --random_seed=112986622569797306072457879734474628454 src/sage/doctest/tests/random_seed.rst
+    Running doctests with ID 2020-06-23-23-24-28-14a52269.
+    ...
+    Doctesting 1 file.
+    sage -t --warn-long 89.5 --random_seed=112986622569797306072457879734474628454 src/sage/doctest/tests/random_seed.rst
+    **********************************************************************
+    File "src/sage/doctest/tests/random_seed.rst", line 3, in sage.doctest.tests.random_seed
+    Failed example:
+        randint(5, 10)
+    Expected:
+        9
+    Got:
+        8
+    **********************************************************************
+    1 item had failures:
+       1 of   2 in sage.doctest.tests.random_seed
+        [1 test, 1 failure, 0.00 s]
+    ----------------------------------------------------------------------
+    sage -t --warn-long 89.5 --random_seed=112986622569797306072457879734474628454 src/sage/doctest/tests/random_seed.rst  # 1 doctest failed
+    ----------------------------------------------------------------------
+    Total time for all tests: 0.0 seconds
+        cpu time: 0.0 seconds
+        cumulative wall time: 0.0 seconds
 
 .. _section-optional-doctest-flag:
 
@@ -861,7 +912,7 @@ If you want Sage to detect external software or other capabilities
 (such as magma, latex, internet) automatically and run all of the
 relevant tests, then add ``external``::
 
-    $ sage -t --optional=external src/sage/rings/real_mpfr.pyx 
+    $ sage -t --optional=external src/sage/rings/real_mpfr.pyx
     Running doctests with ID 2016-03-16-14-10-21-af2ebb67.
     Using --optional=external
     External software to be detected: cplex,gurobi,internet,latex,macaulay2,magma,maple,mathematica,matlab,octave,scilab

src/doc/en/reference/repl/options.rst

@@ -135,6 +135,7 @@ Command-line options for Sage
     run the lines which are unlabeled or labeled ``#optional`` or labeled
     ``#optional tag`` for any of the tags given.
   - ``--randorder[=seed]`` -- randomize order of tests
+  - ``--random_seed[=seed]`` -- random seed for fuzzing doctests
   - ``--short[=seconds]`` -- run as many doctests as possible in about 300
     seconds (or the number of seconds given.) This runs the tests for each
     module from the top of the file and skips tests once it exceeds the budget