gh-40443: Run function field TestSuites via pytest
    
* Fix two slow doctest warnings in the CI by moving these tests to
pytest.
* Speed some test suites up by using fewer repeated runs. Nowadays we
run the tests on every PR, so repeated runs within repeated runs are
less valuable.
* Use `QQ` instead of `QQbar` for some tests where this was the original
intention.
* Clean up the docs by eliminating pure-test code from the docstrings.
    
URL: #40443
Reported by: Michael Orlitzky
Reviewer(s): Tobias Diez

Author: Release Manager

src/sage/rings/function_field/function_field.py

@@ -122,19 +122,6 @@
     sage: m(y)^2 + m(y) + m(x) + 1/m(x)         # long time (8s)
     O(s^5)
 
-TESTS::
-
-    sage: TestSuite(J).run()
-    sage: TestSuite(K).run(max_runs=256)        # long time (10s)                       # needs sage.rings.function_field sage.rings.number_field
-    sage: TestSuite(L).run(max_runs=8)          # long time (25s)                       # needs sage.rings.function_field sage.rings.number_field
-
-    sage: # needs sage.rings.finite_rings sage.rings.function_field
-    sage: TestSuite(M).run(max_runs=8)                                  # long time (35s)
-    sage: TestSuite(N).run(max_runs=8, skip='_test_derivation')         # long time (15s)
-    sage: TestSuite(O).run()
-    sage: TestSuite(R).run()
-    sage: TestSuite(S).run()                                            # long time (4s)
-
 Global function fields
 ----------------------
 
@@ -301,10 +288,12 @@ def __init__(self, base_field, names, category=FunctionFields()):
         """
         Initialize.
 
-        TESTS::
+        EXAMPLES::
+
+            sage: K = FunctionField(QQ, 'z')
+            sage: K
+            Rational function field in z over Rational Field
 
-            sage: K.<x> = FunctionField(QQ)
-            sage: TestSuite(K).run()               # long time (3s)
         """
         Field.__init__(self, base_field, names=names, category=category)
 
@@ -747,7 +736,8 @@ def _test_derivation(self, **options):
         EXAMPLES::
 
             sage: K.<x> = FunctionField(QQ)
-            sage: TestSuite(K).run()    # indirect doctest, long time (3s)
+            sage: K._test_derivation()  # long time
+
         """
         tester = self._tester(**options)
         S = tester.some_elements()

src/sage/rings/function_field/function_field_test.py

@@ -0,0 +1,116 @@
+import pytest
+
+from sage.rings.finite_rings.finite_field_constructor import FiniteField
+from sage.rings.function_field.constructor import FunctionField
+from sage.rings.polynomial.polynomial_ring_constructor import PolynomialRing
+from sage.rings.rational_field import QQ
+
+
+@pytest.fixture
+def F():
+    return FunctionField(QQ, 'x')
+
+
+@pytest.fixture
+def J():
+    return FunctionField(FiniteField(5), 'x')
+
+
+@pytest.fixture
+def K():
+    return FunctionField(FiniteField(5**2,'a'), 'x')
+
+
+@pytest.fixture
+def L(F):
+    x = F.gen()
+    Y = PolynomialRing(F, 'Y').gen()
+    return F.extension(Y**2 + Y + x + 1/x, 'y')
+
+
+@pytest.fixture
+def M(K, R, S):
+    x = K.gen()
+    y = R.gen()
+    L = K.extension(y**3 - (x**3 + 2*x*y + 1/x))
+    t = S.gen()
+    return L.extension(t**2 - x*y)
+
+
+@pytest.fixture
+def N(K):
+    return FunctionField(K, 'u')
+
+
+@pytest.fixture
+def O(L):
+    return L.maximal_order()
+
+
+@pytest.fixture
+def R(K):
+    return PolynomialRing(K, 'y')
+
+
+@pytest.fixture
+def S(K, R):
+    x = K.gen()
+    y = R.gen()
+    L = K.extension(y**3 - (x**3 + 2*x*y + 1/x))
+    return PolynomialRing(L, 't')
+
+
+@pytest.fixture
+def T(F):
+    return PolynomialRing(F, 'Y')
+
+
+# Use strings for the fixture names here, and then later convert them
+# to the actual fixture objects using request.getfixturevalue(). This
+# is a workaround for being unable to pass fixtures directly as
+# parameters:
+#
+#   https://github.com/pytest-dev/pytest/issues/349
+#
+pairs = [ ("J", None),
+          ("K", 16),
+          ("L", 2),
+          ("M", 1),
+          ("N", 1),
+          ("O", None),
+          ("T", None),
+          ("S", 8) ]
+
+
+@pytest.mark.parametrize("ff,max_runs", pairs)
+def test_function_field_testsuite(ff, max_runs, request):
+    r"""
+    Run the TestSuite() on some function fields that are
+    constructed in the documentation. They are slow, random, and not
+    intended for end users. All of this makes them more appropriate to
+    be run separately, here, than in the doctests.
+
+    INPUT:
+
+    The inputs are essentially all fixtures.
+
+    - ``ff`` -- string; a function field fixture name
+    - ``max_runs`` -- integer; the maxmimum number of times to
+      repeat the test suite
+    - ``request`` -- fixture; a pytest built-in
+
+    """
+    # The sage.misc.sage_unittest.TestSuite import is local to avoid
+    # pytest warnings.
+    from sage.misc.sage_unittest import TestSuite
+
+    # Convert the fixture name (string) to an actual object using the
+    # built-in "request" fixture.
+    ff = request.getfixturevalue(ff)
+
+    # Pass max_runs only if it's not None; otherwise use the default
+    run_args = { "verbose": True, "raise_on_failure": True }
+    if max_runs:
+        run_args["max_runs"] = max_runs
+
+    TestSuite(ff).run(**run_args)

src/sage/rings/function_field/meson.build

@@ -12,6 +12,7 @@ py.install_sources(
   'function_field.py',
   'function_field_polymod.py',
   'function_field_rational.py',
+  'function_field_test.py',
   'ideal.py',
   'ideal_polymod.py',
   'ideal_rational.py',