docs: math testing infos

tests/unitary/math/README.md

@@ -0,0 +1,26 @@
+# Math contract tests
+
+```
+math
+├── conftest.py - "Fixtures for new and old math contracts."
+├── fuzz_multicoin_curve.py
+├── misc.py
+├── test_cbrt.py
+├── test_exp.py
+├── test_get_p.py
+├── test_get_y.py
+├── test_log2.py
+├── test_newton_D.py
+├── test_newton_D_ref.py
+├── test_newton_y.py
+└── test_packing.py - "Testing unpacking for (2, 3)-tuples"
+```
+
+### Fuzzing parallelization
+Due to the nature of the math involved in curve pools (i.e. analytical solutions for equations not always availble), we often require on approximation methods to solve these equations numerically. Testing this requires extensive fuzzing which can be very time consuming sometimes. Hypothesis does not support test parallelisation and this is why in the code you might often see test parametrisation as a hacky way to obtain parallel fuzzing:
+
+```python
+@pytest.mark.parametrize(
+    "_tmp", range(N_CASES)
+)  # Parallelisation hack (more details in folder's README)
+```

tests/unitary/math/test_get_y.py

@@ -65,7 +65,7 @@ def test_get_y_revert(math_contract):
 
 @pytest.mark.parametrize(
     "_tmp", range(N_CASES)
-)  # Create N_CASES independent test instances.
+)  # Parallelisation hack (more details in folder's README)
 @given(
     A=st.integers(min_value=MIN_A, max_value=MAX_A),
     D=st.integers(
@@ -100,7 +100,7 @@ def calculate_F_by_y0(y0):
             assert gamma > 2 * 10**16
             return
         else:  # Did not converge?
-           raise
+            raise
     pytest.gas_original += math_unoptimized._computation.get_gas_used()
 
     try:
@@ -114,7 +114,10 @@ def calculate_F_by_y0(y0):
             if gamma > 2 * 10**16:
                 lim_mul = lim_mul * 2 * 10**16 // gamma
             frac = result_original * 10**18 // D
-            if abs(frac - 10**36 // 2 // lim_mul) < 100 or abs(frac - lim_mul // 2) < 100:
+            if (
+                abs(frac - 10**36 // 2 // lim_mul) < 100
+                or abs(frac - lim_mul // 2) < 100
+            ):
                 return
             else:
                 raise

tests/unitary/math/test_newton_D.py

@@ -171,7 +171,11 @@ def _test_newton_D(
         raise  # this is a problem
 
     # dy should be positive
-    if result_get_y < X[j] and result_get_y / D > MIN_XD / 1e18 and result_get_y / D < MAX_XD / 1e18:
+    if (
+        result_get_y < X[j]
+        and result_get_y / D > MIN_XD / 1e18
+        and result_get_y / D < MAX_XD / 1e18
+    ):
 
         price_scale = (btcScalePrice, ethScalePrice)
         y = X[j]

tests/unitary/math/test_newton_D_ref.py

@@ -56,7 +56,7 @@ def inv_target_decimal_n2(A, gamma, x, D):
 
 @pytest.mark.parametrize(
     "_tmp", range(N_CASES)
-)  # Create N_CASES independent test instances.
+)  # Parallelisation hack (more details in folder's README)
 @given(
     A=st.integers(min_value=MIN_A, max_value=MAX_A),
     D=st.integers(

tests/unitary/math/test_newton_y.py

@@ -47,7 +47,7 @@ def test_iteration_diff(math_large_gamma, A, D, xD, yD, gamma, j):
     # - measures how many iterations it takes for the
     #   old value to converge between the two versions
     # - makes sure that we're converging to the correct value
-    # - use hypothesis.note to have some clear statistics about
+    # - use hypothesis.event to have some clear statistics about
     #   the differences in divergence
     # X = [D * xD // 10**18, D * yD // 10**18]
     # math_large_gamma.newton_y(A, gamma, X, D, j)