Merge pull request #64 from tylerriccio33/assertion-method

Add Explicit Assertion Method to `Validate` for Test Suites

Author: rich-iannone

docs/_quarto.yml

@@ -127,6 +127,7 @@ quartodoc:
         - name: Validate.get_sundered_data
         - name: Validate.get_data_extracts
         - name: Validate.all_passed
+        - name: Validate.assert_passing
         - name: Validate.n
         - name: Validate.n_passed
         - name: Validate.n_failed

pointblank/validate.py

@@ -5047,6 +5047,51 @@ def all_passed(self) -> bool:
         """
         return all(validation.all_passed for validation in self.validation_info)
 
+    def assert_passing(self) -> None:
+        """
+        Raise an `AssertionError` if all tests are not passing.
+
+        The `assert_passing()` method will raise an `AssertionError` if a test does not pass. This
+        method simply wraps `all_passed` for more ready use in test suites. The method does not
+        preserve information or the object itself, and must be further investigated.
+
+        Raises
+        -------
+        AssertionError
+            If any validation step has failing test units.
+
+        Examples
+        --------
+        In the example below, we'll use a simple Polars DataFrame with three columns (`a`, `b`, and
+        `c`). There will be three validation steps, and the second step will have a failing test
+        unit (the value `10` isn't less than `9`). After interrogation, the `assert_passing()`
+        method is used to assert that all validation steps passed perfectly.
+
+        ```{python}
+
+        tbl = pl.DataFrame(
+            {
+            "a": [1, 2, 9, 5],
+            "b": [5, 6, 10, 3],
+            "c": ["a", "b", "a", "a"],
+            }
+        )
+
+        validation = (
+            pb.Validate(data=tbl)
+            .col_vals_gt(columns="a", value=0)
+            .col_vals_lt(columns="b", value=9)
+            .col_vals_in_set(columns="c", set=["a", "b"])
+            .interrogate()
+        )
+
+        validation.assert_passing()
+        ```
+        """
+        if not self.all_passed():
+            msg = "All tests did not pass."
+            raise AssertionError(msg)
+
     def n(self, i: int | list[int] | None = None, scalar: bool = False) -> dict[int, int] | int:
         """
         Provides a dictionary of the number of test units for each validation step.

tests/test_validate.py

@@ -5,6 +5,9 @@
 import re
 from unittest.mock import patch
 import pytest
+import itertools
+from functools import partial
+import contextlib
 
 import pandas as pd
 import polars as pl
@@ -7604,3 +7607,56 @@ def test_get_schema_step_report_25_5(tbl_schema_tests, snapshot):
 
     # Take snapshot of the report DataFrame
     snapshot.assert_match(str(report_df), "schema_step_report_25-5.txt")
+
+
+@pytest.mark.parametrize(('tbl','should_pass'), itertools.product(TBL_LIST, [True, False]))
+def test_assert_passing(request, tbl : str , *, should_pass: bool) -> None:
+    tbl = request.getfixturevalue(tbl)
+
+    if should_pass:
+        val = 0 # should always pass
+        catcher = contextlib.nullcontext
+    else:
+        val = 100 # should always fail
+        catcher = partial(pytest.raises, AssertionError, match = "All tests did not pass")
+
+
+    v = Validate(tbl).col_vals_gt(columns="x", value=val).interrogate()
+
+
+    try:
+        assert v.all_passed() == should_pass
+    except AssertionError:
+        pytest.mark.skip(reason="Unexpected result invalidating the test. Please review.")
+
+    with catcher():
+        v.assert_passing() # should not raise since all passing
+
+def test_assert_passing_example() -> None:
+    tbl = pl.DataFrame(
+        {
+        "a": [1, 2, 9, 5],
+        "b": [5, 6, 10, 3],
+        "c": ["a", "b", "a", "a"],
+        }
+    )
+
+    validation = (
+        Validate(data=tbl)
+        .col_vals_gt(columns="a", value=0)
+        .col_vals_lt(columns="b", value=9) # this step will not pass
+        .col_vals_in_set(columns="c", set=["a", "b"])
+        .interrogate()
+    )
+    with pytest.raises(AssertionError, match = "All tests did not pass"):
+        validation.assert_passing()
+
+    passing_validation = (
+        Validate(data=tbl)
+        .col_vals_gt(columns="a", value=0)
+        # now, the invalid step passes
+        .col_vals_in_set(columns="c", set=["a", "b"])
+        .interrogate()
+    )
+
+    passing_validation.assert_passing()