bean-test 0.1.0__py3-none-any.whl

bean/test.py

@@ -0,0 +1,1573 @@
+# ============================================================================ #
+#                                                                              #
+#                               ,---.      ,---.                               #
+#                              /     `-<>-'  :D \                              #
+#                              |                |                              #
+#                               . .            .                               #
+#                               .`-~~~~~~~~~~-'                                #
+#                                                                              #
+#                            Bean there, done that.                            #
+#                                                                              #
+# ============================================================================ #
+
+__version__ = "0.1.0"
+__doc__     = "Tiny test framework"
+__author__  = "numen-0"
+__license__ = "MIT"
+
+# ------------------------------------------------------------------------------
+# api
+# ------------------------------------------------------------------------------
+
+__all__ = [
+    "Lab", "register", "inline",
+    "expect",
+    "rand",
+]
+
+# Hack: Hide imported stuff for `dir(module)`
+__dir__ = lambda: __all__
+
+# ------------------------------------------------------------------------------
+# imports
+# ------------------------------------------------------------------------------
+
+import dataclasses  as _dataclasses
+import datetime     as _datetime
+import random       as _random
+import time         as _time
+import typing       as _
+
+# ------------------------------------------------------------------------------
+# lab
+# ------------------------------------------------------------------------------
+
+class Lab:
+
+    #* vars
+
+    EMPTY_CASE: tuple[tuple[()]] = ((),)
+    tests: dict[str, list[TestCase]] = {}
+
+    #* types
+
+    type TestFn = _.Callable[[], None]
+    type CaseTestFn[*Ts] = _.Callable[[*Ts], None]
+    type InternalTestFn[*Ts] = _.Callable[[*Ts], None]
+
+    @_dataclasses.dataclass(frozen=True, slots=True)
+    class Report:
+        total: int
+        passed: int
+        failed: int
+        skipped: int
+        results: dict[str, list[tuple[Lab.TestCase, Lab.TestResult]]]
+
+        def __bool__(self) -> bool:
+            return self.ok
+
+        @property
+        def ok(self) -> bool:
+            return self.failed == 0
+
+        @property
+        def namespaces(self) -> set[str]:
+            return set(self.results.keys())
+
+        def failures(
+            self,
+        ) -> list[tuple[Lab.TestCase, Lab.TestResult]]:
+            return [
+                (test, result)
+                for results in self.results.values()
+                for test, result in results
+                if not result.ok and not test.failable
+            ]
+
+        #* sugar
+
+        def print(
+            self,
+            *,
+            verbosity: _.Literal["minimal", "simple", "full"] = "simple",
+            color: bool = True,
+        ) -> bool:
+            import sys
+            import traceback
+
+            errors: list[Exception] = []
+
+            class Color:
+                def __init__(self, code: str):
+                    self.code = code
+
+                def __call__(self, text: str) -> str:
+                    if not color: return text
+                    return f"{self.code}{text}\033[0m"
+
+            GREEN = Color("\033[0;32m")
+            RED = Color("\033[0;31m")
+            YELLOW = Color("\033[0;33m")
+            DIM = Color("\033[0;2m")
+            RESET = Color("\033[0m")
+
+            res_map = {
+                "ok": (
+                    GREEN("+"),
+                    GREEN("O"),
+                    GREEN("[passed]") + "  ",
+                ),
+                "skip": (
+                    DIM("s"),
+                    DIM("S"),
+                    DIM("[disabled]"),
+                ),
+                "warn": (
+                    YELLOW("f"),
+                    YELLOW("/"),
+                    YELLOW("[ignored]") + " ",
+                ),
+                "error": (
+                    RED("F"),
+                    RED("X"),
+                    RED("[error]") + "   ",
+                ),
+            }
+
+            def p_res(test: Lab.TestCase, result: Lab.TestResult):
+                duration = result.duration * 1000
+
+                if result.skipped:
+                    status = "skip"
+                elif result.ok:
+                    status = "ok"
+                elif result.failable:
+                    status = "warn"
+                else:
+                    status = "error"
+
+                    if result.exception is not None:
+                        errors.append(result.exception)
+
+                symbol, mark, label  = res_map[status]
+
+                match verbosity:
+                    case "minimal":
+                        print(symbol, end="")
+                    case "simple":
+                        print(f"  - {test.name:{name_width}} : {mark}")
+                    case "full":
+                        if not test.is_cased:
+                            print(f"  - {test.name:{name_width}} : {label} "
+                                  f"[{duration:.2f} ms]")
+                        else:
+                            print(f"  - {test.name:{name_width}} : {label} "
+                                  f"([{result.indx}]={result.case!r}) "
+                                  f"[{duration:.2f} ms]")
+
+            all_results = sorted(
+                [
+                    (namespace, sorted(results, key=lambda t: t[0].name))
+                    for namespace, results in self.results.items()
+                ],
+                key=lambda t: t[0], # namespace
+            )
+
+            name_width = min(32, max(
+                (
+                    len(test.name)
+                    for _, results in all_results
+                    for test, _ in results
+                ),
+                default=0,
+            ))
+
+            for namespace, results in all_results:
+                match verbosity:
+                    case "minimal": pass
+                    case "simple":  print(f"{namespace}:")
+                    case "full":    print(f"{namespace} [{len(results)}]:")
+
+                for test, result in results:
+                    p_res(test, result)
+
+            if verbosity == "minimal":
+                print()
+
+            print("=" * 80)
+
+            if errors:
+                eg = ExceptionGroup("Some test failed", errors)
+
+                if color: print(RED.code, end="")
+                traceback.print_exception(eg, file=sys.stdout)
+                if color: print(RESET.code, end="")
+
+                print("=" * 80)
+
+            print(
+                f"{self.total} tests: "
+                f"{self.passed} passed, "
+                f"{self.failed} failed, "
+                f"{self.skipped} skipped"
+            )
+
+            return self.ok
+
+    @_dataclasses.dataclass(frozen=True, slots=True)
+    class TestResult[*Ts]:
+        indx: int
+        case: tuple[*Ts]
+        duration: float
+        exception: Exception | None = None
+
+        failable: bool = False
+        skipped: bool = False
+
+        @property
+        def ok(self) -> bool:
+            return self.skipped or self.exception is None
+
+    @_dataclasses.dataclass(frozen=True, slots=True)
+    class TestCase[*Ts]:
+        fn: Lab.InternalTestFn[*Ts]
+        name: str
+        cases: _.Sequence[tuple[*Ts]]
+
+        enabled: bool
+        failable: bool
+
+        @property
+        def is_cased(self) -> bool:
+            return self.cases != Lab.EMPTY_CASE
+
+        def run(self) -> list[Lab.TestResult[*Ts]]:
+            results = []
+
+            for i, case in enumerate(self.cases):
+                ex = None
+                start = _time.perf_counter()
+
+                try:
+                    self.fn(*case)
+
+                except Exception as e:
+                    ex = e
+
+                results.append(Lab.TestResult(
+                    indx=i,
+                    case=case,
+                    duration=_time.perf_counter() - start,
+                    exception=ex,
+                    failable=self.failable,
+                ))
+
+            return results
+
+    #* methods
+
+    @classmethod
+    def report(
+        cls,
+        namespaces: str | _.Collection[str] | None = None,
+        failable: _.Literal["ignore", "fail"] = "ignore",
+    ) -> Report:
+        if namespaces is None:
+            selected = cls.tests.keys()
+        elif isinstance(namespaces, str):
+            selected = (namespaces,)
+        else:
+            selected = namespaces
+
+        total, passed, failed, skipped = 0, 0, 0, 0
+        results: dict[str, list[tuple[Lab.TestCase, Lab.TestResult]]] = {}
+
+        for namespace in selected:
+            namespace_results: list[tuple[Lab.TestCase, Lab.TestResult]] = []
+            tests: list[Lab.TestCase] = cls.tests.get(namespace, [])
+
+            for test in tests:
+                if not test.enabled:
+                    skipped += len(test.cases)
+
+                    namespace_results.extend([
+                        (test, Lab.TestResult(
+                            indx=i,
+                            case=case,
+                            duration=-1,
+                            exception=None,
+                            failable=test.failable,
+                            skipped=True,
+                        )) for i, case in enumerate(test.cases)
+                    ])
+                    continue
+
+                for result in test.run():
+                    if result.ok or (test.failable and failable == "ignore"):
+                        passed += 1
+
+                    else:
+                        failed += 1
+
+                    namespace_results.append((test, result))
+
+            results[namespace] = namespace_results
+            total += len(namespace_results)
+
+        return Lab.Report(
+            total=total,
+            passed=passed,
+            failed=failed,
+            skipped=skipped,
+            results=results,
+        )
+
+    #* sugar
+
+    @classmethod
+    def print(
+        cls,
+        namespaces: str | _.Collection[str] | None = None,
+        *,
+        failable: _.Literal["ignore", "fail"] = "ignore",
+        verbosity: _.Literal["minimal", "simple", "full"] = "minimal",
+        color: bool = True,
+    ) -> bool:
+        return Lab.report(
+            namespaces=namespaces,
+            failable=failable,
+        ).print(
+            verbosity=verbosity,
+            color=color,
+        )
+
+# ------------------------------------------------------------------------------
+# test
+# ------------------------------------------------------------------------------
+
+@_.overload
+def register[*Ts](
+    namespace: str = "default",
+    *,
+    cases: _.Sequence[tuple[*Ts]],
+    enabled: bool = True,
+    failable: bool = False,
+) -> _.Callable[[Lab.CaseTestFn[*Ts]], Lab.CaseTestFn[*Ts]]: ...
+
+@_.overload
+def register[*Ts](
+    namespace: str = "default",
+    *,
+    cases: None = None,
+    enabled: bool = True,
+    failable: bool = False,
+) -> _.Callable[[Lab.TestFn], Lab.TestFn]: ...
+
+def register[*Ts](
+    namespace: str = "default",
+    *,
+    cases: _.Sequence[tuple[*Ts]]|None = None,
+    enabled: bool = True,
+    failable: bool = False,
+) -> _.Union[
+    _.Callable[[Lab.TestFn], Lab.TestFn],
+    _.Callable[[Lab.CaseTestFn[*Ts]], Lab.CaseTestFn[*Ts]],
+]:
+    """ Register a test, optionally parameterized by cases. """
+
+    ns = Lab.tests.setdefault(namespace, [])
+
+    if cases is None:
+        def d1(fn: Lab.TestFn):
+
+            ns.append(
+                Lab.TestCase[()](
+                    fn=lambda *case: fn(),
+                    name=fn.__name__,
+                    cases=Lab.EMPTY_CASE,
+                    enabled=enabled,
+                    failable=failable,
+                )
+            )
+
+            return fn
+        return d1
+
+    def d2(fn: Lab.CaseTestFn[*Ts]):
+
+        ns.append(
+            Lab.TestCase[*Ts](
+                fn=fn,
+                name=fn.__name__,
+                cases=cases,
+                enabled=enabled,
+                failable=failable,
+            )
+        )
+
+        return fn
+
+    return d2
+
+#* sugar
+
+@_.overload
+def inline[*Ts](
+    *,
+    cases: _.Sequence[tuple[*Ts]],
+    enabled: bool = True,
+    failable: bool = False,
+) -> _.Callable[[Lab.CaseTestFn[*Ts]], Lab.CaseTestFn[*Ts]]: ...
+
+@_.overload
+def inline[*Ts](
+    *,
+    cases: None = None,
+    enabled: bool = True,
+    failable: bool = False,
+) -> _.Callable[[Lab.TestFn], Lab.TestFn]: ...
+
+def inline[*Ts](
+    *,
+    cases: _.Sequence[tuple[*Ts]]|None = None,
+    enabled: bool = True,
+    failable: bool = False,
+) -> _.Union[
+    _.Callable[[Lab.TestFn], Lab.TestFn],
+    _.Callable[[Lab.CaseTestFn[*Ts]], Lab.CaseTestFn[*Ts]],
+]:  return register(
+        namespace="inline",
+        cases=cases,
+        enabled=enabled,
+        failable=failable,
+    )
+
+# ------------------------------------------------------------------------------
+# rand
+# ------------------------------------------------------------------------------
+
+def _instantiate[T](*args, **kwargs) -> _.Callable[[type[T]], T]:
+
+    def decorator(cls: type[T]) -> T:
+        return cls(*args, **kwargs)
+
+    return decorator
+
+@_instantiate()
+class rand:
+
+    type Factory[T] = _.Callable[[_random.Random], T]
+
+    CHARS: str = (
+        "abcdefghijklmnopqrstuvwxyz"
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+        "0123456789"
+    )
+
+    @staticmethod
+    def cases(
+        *factories: Factory,
+        count: int = 1,
+        seed: int|float|str|bytes|bytearray|None = None
+    ) -> _.Generator[tuple[_.Any, ...], None, None]:
+        """ Generate test cases from random factories. """
+        rng = _random.Random(seed)
+
+        return (
+            tuple(factory(rng) for factory in factories)
+            for _ in range(count)
+        )
+
+    @staticmethod
+    def product[T](
+        *values: _.Iterable[T],
+    ) -> _.Iterable[tuple[T, ...]]:
+        """ Return the cartesian product of the given iterables. """
+        import itertools
+        return itertools.product(*values)
+
+    @staticmethod
+    def choice[T](*values: T) -> Factory[T]:
+        """ Return factory that randomly chooses one of the values. """
+        if not values:
+            raise ValueError("choice() requires at least one value")
+
+        return lambda rng: rng.choice(values)
+
+    @staticmethod
+    def bind[T](
+        factory: _.Callable[..., T],
+        **kwargs: _.Any,
+    ) -> Factory[T]:
+        """ Bind keyword arguments to factory. """
+        return lambda rng: factory(rng, **kwargs)
+
+    @_.overload
+    def __call__[T](
+        self,
+        typ: type[T],
+        *,
+        min: int|float|None = None,
+        max: int|float|None = None,
+    ) -> Factory[T]: ...
+
+    @_.overload
+    def __call__(
+        self,
+        typ: type[bytes],
+        *,
+        n: int|None = None,
+    ) -> Factory[bytes]: ...
+
+    @_.overload
+    def __call__(
+        self,
+        typ: type[str],
+        *,
+        min: int|None = None,
+        max: int|None = None,
+        chars: str = CHARS,
+    ) -> Factory[str]: ...
+
+    @_.overload
+    def __call__(
+        self,
+        typ: type[_datetime.date],
+        *,
+        min: _datetime.date|None = None,
+        max: _datetime.date|None = None,
+    ) -> Factory[_datetime.date]: ...
+
+    @_.overload
+    def __call__(
+        self,
+        typ: _.Any,
+        /,
+        **kwargs,
+    ) -> Factory[_.Any]: ...
+
+    def __call__[T](
+        self,
+        typ: type[T],
+        *,
+        min: int|float|_datetime.date|None = None,
+        max: int|float|_datetime.date|None = None,
+        n: int|None = None,
+        chars: str = CHARS,
+        **kwargs,
+    ) -> Factory[T]:
+        origin = _.get_origin(typ)
+        if origin is _.Literal:
+            values = _.get_args(typ)
+            return rand.choice(*values)
+
+        import enum, inspect, uuid
+
+        r: rand.Factory
+
+        if typ is bool:
+            r = lambda rng: bool(rng.getrandbits(1))
+
+        elif typ is int:
+            assert not isinstance(min, _datetime.date)
+            assert not isinstance(max, _datetime.date)
+            a = int(min) if min is not None else 0
+            b = int(max) if max is not None else 20
+            r = lambda rng: rng.randint(a, b)
+
+        elif typ is float:
+            assert not isinstance(min, _datetime.date)
+            assert not isinstance(max, _datetime.date)
+            a = float(min) if min is not None else 0.0
+            b = float(max) if max is not None else 1.0
+            r = lambda rng: rng.uniform(a, b)
+
+        elif typ is str:
+            assert not isinstance(min, _datetime.date)
+            assert not isinstance(max, _datetime.date)
+            a = int(min) if min is not None else 0
+            b = int(max) if max is not None else 20
+            r = lambda rng: "".join(rng.choices(chars, k=rng.randint(a, b)))
+
+        elif inspect.isclass(typ) and issubclass(typ, enum.Enum):
+            r = rand.choice(*tuple(typ))
+
+        elif typ is bytes:
+            n = int(n) if n is not None else 32
+            r = lambda rng: rng.randbytes(n=n)
+
+        elif typ is _datetime.date:
+            lo = min or _datetime.date.today()
+            hi = max or lo
+
+            if not isinstance(lo, _datetime.date):
+                raise TypeError("date min must be a date")
+
+            if not isinstance(hi, _datetime.date):
+                raise TypeError("date max must be a date")
+
+            lo, hi = lo.toordinal(), hi.toordinal()
+            r = lambda rng: _datetime.date.fromordinal(rng.randint(lo, hi))
+
+        elif typ is uuid.UUID:
+            r = lambda rng: uuid.UUID(int=rng.getrandbits(128))
+
+        else:
+            raise TypeError(f"Unsupported random factory: {typ!r}")
+
+        return _.cast(rand.Factory[T], r)
+
+# ------------------------------------------------------------------------------
+# expect
+# ------------------------------------------------------------------------------
+
+class expect:
+    __slots__ = ("value",)
+
+    def __init__(self, value: _.Any):
+        self.value = value
+
+    #* misc
+
+    def Check(
+        self,
+        predicate: _.Callable[[_.Any], bool],
+        msg: str | None = None,
+    ) -> _.Self:
+        if not predicate(self.value):
+            raise AssertionError(
+                msg or f"predicate failed for {self.value!r}"
+            )
+
+        return self
+
+    def Set(
+        self,
+        value: _.Any,
+    ) -> _.Self:
+        self.value = value
+        return self
+
+    def Map(
+        self,
+        fn: _.Callable[[_.Any], _.Any],
+    ) -> _.Self:
+        self.value = fn(self.value)
+        return self
+
+    def MapEach(
+        self,
+        fn: _.Callable[[_.Any], _.Any],
+        factory: _.Callable[[_.Iterable], _.Iterable] = list,
+    ) -> _.Self:
+        self.IsIterable()
+        self.value = factory(map(fn, self.value))
+        return self
+
+    #* context
+
+    class Raises:
+        """
+        Context manager asserting that one of the given exceptions is raised.
+        """
+
+        def __init__(self, *exc_types: type[BaseException]):
+            self.exc_types = exc_types
+            self.exception: BaseException | None = None
+
+        def __enter__(self) -> expect.Raises:
+            return self
+
+        def __exit__(self, exc_type, exc, tb) -> bool:
+            names = ", ".join(t.__name__ for t in self.exc_types)
+
+            if exc is None:
+                raise AssertionError(
+                    f"expected {names} to be raised, but nothing was raised"
+                )
+
+            if not isinstance(exc, self.exc_types):
+                raise AssertionError(
+                    f"expected {names} to be raised, "
+                    f"got {type(exc).__name__}: {exc}"
+                ) from exc
+
+            self.exception = exc
+            return True
+
+    #* truthiness
+
+    def Truthy(
+        self,
+        msg: str | None = None,
+    ) -> _.Self:
+        if not self.value:
+            raise AssertionError(
+                msg or f"expected truthy expression, got {self.value!r}"
+            )
+        return self
+
+    def Falsy(
+        self,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value:
+            raise AssertionError(
+                msg or f"expected falsy expression, got {self.value!r}"
+            )
+
+        return self
+
+    def Empty(self) -> _.Self:
+        try:
+            length = len(self.value) # type: ignore
+        except TypeError:
+            raise TypeError(
+                f"expected a sized value, got {type(self.value).__name__}"
+            )
+
+        if length != 0:
+            raise AssertionError(
+                f"expected {self.value!r} to be empty, got length {length}"
+            )
+
+        return self
+
+
+    def NotEmpty(self) -> _.Self:
+        try:
+            length = len(self.value) # type: ignore
+        except TypeError:
+            raise TypeError(
+                f"expected a sized value, got {type(self.value).__name__}"
+            )
+
+        if length == 0:
+            raise AssertionError(
+                f"expected {self.value!r} to not be empty"
+            )
+
+        return self
+
+    #* membership
+
+    def In(
+        self,
+        container: _.Container[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value not in container:
+            raise AssertionError(
+                msg or f"expected {self.value!r} to be in {container!r}"
+            )
+
+        return self
+
+    def NotIn(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value in expected:
+            raise AssertionError(
+                msg or f"expected {self.value!r} to not be in {expected!r}"
+            )
+
+        return self
+
+    def HasAttr(
+        self,
+        attr: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        if not hasattr(self.value, attr):
+            raise AssertionError(
+                msg or f"expected {self.value!r} to have attribute '{attr!r}'"
+            )
+
+        return self
+
+    def NotHasAttr(
+        self,
+        attr: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        if hasattr(self.value, attr):
+            raise AssertionError(
+                msg
+                or f"expected {self.value!r} not to have attribute '{attr!r}'"
+            )
+
+        return self
+
+    #* equality
+
+    def Equal(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value != expected:
+            raise AssertionError(
+                msg or f"expected {self.value!r} == {expected!r}"
+            )
+
+        return self
+
+    def NotEqual(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value == expected:
+            raise AssertionError(
+                msg or f"expected {self.value!r} != {expected!r}"
+            )
+
+        return self
+
+    def Greater(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value <= expected:
+            raise AssertionError(
+                msg or f"expected {self.value!r} > {expected!r}"
+            )
+
+        return self
+
+    def GreaterEqual(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value < expected:
+            raise AssertionError(
+                msg or f"expected {self.value!r} >= {expected!r}"
+            )
+
+        return self
+
+    def Less(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value >= expected:
+            raise AssertionError(
+                msg or f"expected {self.value!r} < {expected!r}"
+            )
+
+        return self
+
+    def LessEqual(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value > expected:
+            raise AssertionError(
+                msg or f"expected {self.value!r} <= {expected!r}"
+            )
+
+        return self
+
+    def AlmostEqual(
+        self,
+        expected: float,
+        msg: str | None = None,
+        *,
+        rel_tol: float = 1e-9,
+        abs_tol: float = 0.0,
+    ) -> _.Self:
+        import math
+        self.IsNumeric()
+
+        if not math.isclose(
+            self.value, # type:ignore
+            expected,
+            rel_tol=rel_tol,
+            abs_tol=abs_tol,
+        ):
+            raise AssertionError(
+                msg or f"expected {self.value!r} == {expected!r} (almost)"
+            )
+
+        return self
+
+    def NotAlmostEqual(
+        self,
+        expected: float,
+        msg: str | None = None,
+        *,
+        rel_tol: float = 1e-9,
+        abs_tol: float = 0.0,
+    ) -> _.Self:
+        import math
+        self.IsNumeric()
+
+        if math.isclose(
+            self.value, # type:ignore
+            expected,
+            rel_tol=rel_tol,
+            abs_tol=abs_tol,
+        ):
+            raise AssertionError(
+                msg or f"expected {self.value!r} != {expected!r} (almost)"
+            )
+
+        return self
+
+    #* strings
+
+    def StartsWith(
+        self,
+        expected: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        self.IsString()
+
+        if not self.value.startswith(expected): # type:ignore
+            raise AssertionError(
+                msg or f"expected {self.value!r} to start with {expected!r}"
+            )
+
+        return self
+
+    def NotStartsWith(
+        self,
+        expected: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        self.IsString()
+
+        if self.value.startswith(expected): # type:ignore
+            raise AssertionError(
+                msg or f"expected {self.value!r} to not start with {expected!r}"
+            )
+
+        return self
+
+    def EndsWith(
+        self,
+        expected: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        self.IsString()
+
+        if not self.value.endswith(expected): # type:ignore
+            raise AssertionError(
+                msg or f"expected {self.value!r} to end with {expected!r}"
+            )
+
+        return self
+
+    def NotEndsWith(
+        self,
+        expected: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        self.IsString()
+
+        if self.value.endswith(expected): # type:ignore
+            raise AssertionError(
+                msg or f"expected {self.value!r} to not end with {expected!r}"
+            )
+
+        return self
+
+    def Regex(
+        self,
+        expected: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        import re
+        self.IsString()
+
+        if re.search(expected, self.value) is None: # type:ignore
+            raise AssertionError(
+                msg or f"expected {self.value!r} to match regex {expected!r}"
+            )
+
+        return self
+
+    def NotRegex(
+        self,
+        expected: str,
+        msg: str | None = None,
+    ) -> _.Self:
+        import re
+        self.IsString()
+
+        if re.search(expected, self.value) is not None: # type:ignore
+            raise AssertionError(
+                msg or f"expected {self.value!r} not to match regex {expected!r}"
+            )
+
+        return self
+
+    #* quantifiers
+
+    def All(
+        self,
+        predicate: _.Callable[[_.Any], bool],
+        msg: str | None = None,
+    ) -> _.Self:
+        self.IsIterable()
+
+        for index, value in enumerate(self.value):
+            if not predicate(value):
+                raise AssertionError(
+                    msg
+                    or "expected all items to satisfy predicate, "
+                       f"failed at index {index}: {value!r}"
+                )
+
+        return self
+
+    def Any(
+        self,
+        predicate: _.Callable[[_.Any], bool],
+        msg: str | None = None,
+    ) -> _.Self:
+        self.IsIterable()
+
+        for index, value in enumerate(self.value):
+            if predicate(value):
+                return self
+
+        raise AssertionError(
+            msg or "expected any item to satisfy predicate, but none did"
+        )
+
+    def NotAny(
+        self,
+        predicate: _.Callable[[_.Any], bool],
+        msg: str | None = None,
+    ) -> _.Self:
+        self.IsIterable()
+
+        for index, value in enumerate(self.value):
+            if predicate(value):
+                raise AssertionError(
+                    msg
+                    or "expected no items to satisfy predicate, "
+                       f"first match at index {index}: {value!r}"
+                )
+
+        return self
+
+    def IsSorted(
+        self,
+        *,
+        key: _.Callable[[_.Any], _.Any] | None = None,
+        reverse: bool = False,
+    ) -> _.Self:
+        """ Assert that an iterable is sorted. """
+        self.IsIterable()
+
+        values = list(self.value)
+
+        if key is None:
+            key = lambda value: value
+
+        for index in range(1, len(values)):
+            previous = key(values[index - 1])
+            current = key(values[index])
+
+            if reverse:
+                if previous < current:
+                    raise AssertionError(
+                        f"expected value to be sorted in reverse at index "
+                        f"{index-1}: {values[index-1]!r} < {values[index]!r}"
+                    )
+            else:
+                if previous > current:
+                    raise AssertionError(
+                        f"expected value to be sorted at index {index - 1}: "
+                        f"{values[index-1]!r} > {values[index]!r}"
+                    )
+
+        return self
+
+    #* collections
+
+    def ContainerEqual(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Equal containers, ignoring order but preserving multiplicity. """
+        self.IsIterable()
+
+        actual, expected = list(self.value), list(expected)
+
+        if len(actual) != len(expected):
+            raise AssertionError(
+                msg or (
+                    f"expected containers of equal size, "
+                    f"got {len(expected)} and {len(actual)}"
+                )
+            )
+
+        for index, value in enumerate(actual):
+            for match_index, candidate in enumerate(expected):
+                if value == candidate:
+                    del expected[match_index]
+                    break
+            else:
+                raise AssertionError(
+                    msg or (
+                        f"self.value item at index {index} "
+                        f"({value!r}) was not found in expected"
+                    )
+                )
+
+        return self
+
+    def SequenceEqual(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Equal sequences. """
+        self.IsIterable()
+
+        actual, expected = list(self.value), list(expected)
+
+        if len(actual) != len(expected):
+            raise AssertionError(
+                msg
+                or "expected sequences of equal length, "
+                   f"got {len(expected)} and {len(actual)}"
+            )
+
+        for index, (got, want) in enumerate(zip(actual, expected)):
+            if got != want:
+                raise AssertionError(
+                    msg
+                    or f"sequences differ at index {index}: "
+                       f"expected {want!r}, got {got!r}"
+                )
+        return self
+
+    def SetEqual(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Equality using set semantics. """
+
+        self.Superset(expected, msg)
+        self.Superset(expected, msg)
+
+        return self
+
+    def NotSetEqual(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Disequality using set semantics. """
+        self.IsIterable()
+
+        bucket_value, bucket_expected = list(self.value), list(expected)
+
+        for index, value in enumerate(bucket_expected):
+            if value not in bucket_value:
+                return self
+
+        for index, value in enumerate(bucket_expected):
+            if value not in bucket_value:
+                return self
+
+        raise AssertionError(
+            msg or f"expected {self.value!r} != {expected!r}"
+        )
+
+    def Subset(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Every item in self.value exists in expected. """
+        self.IsIterable()
+
+        bucket = list(expected)
+        for index, value in enumerate(self.value):
+            if value not in bucket:
+                raise AssertionError(
+                    msg
+                    or f"item at index {index} ({value!r}) "
+                       "was not found in expected, "
+                       f"expected {self.value!r} c {expected}"
+                )
+
+        return self
+
+    def NotSubset(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Not every item in self.value exists in expected. """
+        self.IsIterable()
+
+        bucket = list(expected)
+        for index, value in enumerate(self.value):
+            if value not in bucket:
+                return self
+
+        raise AssertionError(
+            msg or
+            "expected to not be a subset of expected, "
+            "but every item was found, "
+            f"expected {self.value!r} !c {expected}"
+        )
+
+    def Superset(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Every item in expected exists in self.value. """
+        self.IsIterable()
+
+        bucket = list(self.value)
+        for index, value in enumerate(expected):
+            if value not in bucket:
+                raise AssertionError(
+                    msg or (
+                        f"expected item at index {index} ({value!r}) "
+                        f"was not found, "
+                        f"expected {expected!r} c {self.value}"
+                    )
+                )
+
+        return self
+
+    def NotSuperset(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ Not every item in expected exists in self.value. """
+        self.IsIterable()
+
+        bucket = list(self.value)
+        for index, value in enumerate(expected):
+            if value not in bucket:
+                return self
+
+        raise AssertionError(
+            msg or
+            f"expected to not be a superset of expected, "
+            "but every item was found, "
+            f"expected {expected!r} !c {self.value}"
+        )
+
+    def Disjoint(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ No item exists in both containers. """
+        self.IsIterable()
+
+        bucket = list(expected)
+        for index, value in enumerate(self.value):
+            if value in bucket:
+                raise AssertionError(
+                    msg or (
+                        f"expected containers to disjoint, "
+                        f"item at index {index} ({value!r}) exists in both, "
+                        f"expected {expected!r} n {self.value} == 0"
+                    )
+                )
+
+        return self
+
+    def Intersects(
+        self,
+        expected: _.Iterable[_.Any],
+        msg: str | None = None,
+    ) -> _.Self:
+        """ At least one item exists in both containers. """
+        self.IsIterable()
+
+        expected = list(expected)
+
+        for index, value in enumerate(self.value):
+            if value in expected:
+                return self
+
+        raise AssertionError(
+            msg
+            or "expected containers to intersect, "
+               "but they have no items in common"
+                f"expected {expected!r} n {self.value} != 0"
+        )
+
+    #* type / identifiers
+
+    def Is(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value is not expected:
+            raise AssertionError(
+                msg or f"expected {expected!r} (is), got {self.value!r}"
+            )
+
+        return self
+
+    def IsNot(
+        self,
+        expected: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value is expected:
+            raise AssertionError(
+                msg or f"expected {expected!r} (is not), got {self.value!r}"
+            )
+
+        return self
+
+
+    def IsNone(
+        self,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value is not None:
+            raise AssertionError(
+                msg or f"expected None, got {self.value!r}"
+            )
+
+        return self
+
+    def IsNotNone(
+        self,
+        msg: str | None = None,
+    ) -> _.Self:
+        if self.value is None:
+            raise AssertionError(
+                msg or f"expected not None, got {self.value!r}"
+            )
+
+        return self
+
+    def IsInstance(
+        self,
+        cls: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if not isinstance(self.value, cls):
+            raise AssertionError(
+                msg or f"expected {cls!r} (is), got instace {self.value!r}"
+            )
+
+        return self
+
+    def IsNotInstance(
+        self,
+        cls: _.Any,
+        msg: str | None = None,
+    ) -> _.Self:
+        if isinstance(self.value, cls):
+            raise AssertionError(
+                msg or f"expected {cls!r} (is not), got instace {self.value!r}"
+            )
+
+        return self
+
+    def IsNumeric(
+        self
+    ) -> _.Self:
+        if (
+            isinstance(self.value, bool)
+            or not isinstance(self.value, (int, float))
+        ):
+            raise TypeError(
+                f"expected an int or float, got {type(self.value).__name__}"
+            )
+
+        return self
+
+    def IsString(
+        self
+    ) -> _.Self:
+        if not isinstance(self.value, str):
+            raise TypeError(
+                f"expected an str, got {type(self.value).__name__}"
+            )
+
+        return self
+
+    def IsEnum(
+        self
+    ) -> _.Self:
+        import enum, inspect
+
+        if inspect.isclass(self.value) and issubclass(self.value, enum.Enum):
+            return self
+
+        raise TypeError(
+            f"expected an enum, got {type(self.value).__name__}"
+        )
+
+    def IsIterable(
+        self
+    ) -> _.Self:
+        from collections.abc import Iterable
+
+        if not isinstance(self.value, Iterable):
+            raise TypeError(
+                f"expected an iterable, got {type(self.value).__name__}"
+            )
+
+        return self
+
+# ------------------------------------------------------------------------------
+# main
+# ------------------------------------------------------------------------------
+
+if __name__ == "__main__":
+
+    import argparse         as _argparse
+    import importlib.util   as _importlib_util
+    import pathlib          as _pathlib
+    import sys              as _sys
+
+    # Hack: running as __main__ can load the module twice, creating two Lab
+    #       class definitions. Alias it to its real module name.
+    _sys.modules[__spec__.name] = _sys.modules[__name__]
+
+    parser = _argparse.ArgumentParser(
+        prog="python -m bean.test",
+        description="Run bean tests.",
+    )
+
+    parser.add_argument(
+        "roots",
+        nargs="+",
+        metavar="DIR",
+        help="Root directories to search for tests.",
+    )
+
+    parser.add_argument(
+        "-p",
+        "--pattern",
+        default="*.py",
+        help="Pattern used to discover test files.",
+    )
+
+    parser.add_argument(
+        "-r",
+        "--recursive",
+        action="store_true",
+        help="Recursively search root directories for test files.",
+    )
+
+    parser.add_argument(
+        "-i",
+        "--ignore",
+        action="append",
+        nargs="+",
+        default=[[
+            "__pycache__",
+            ".git",
+            ".venv",
+        ]],
+        metavar="DIR",
+        help="Directory name to ignore while recursively searching.",
+    )
+
+    parser.add_argument(
+        "-n",
+        "--namespace",
+        nargs="+",
+        help="Namespaces to run. Use 'inline' for inline tests.",
+    )
+
+    parser.add_argument(
+        "-f",
+        "--failable",
+        action="store_true",
+        help="How failable tests affect the result.",
+    )
+
+    parser.add_argument(
+        "-v",
+        "--verbosity",
+        choices=("minimal", "simple", "full"),
+        default="minimal",
+        help="Report verbosity.",
+    )
+
+    parser.add_argument(
+        "-c",
+        "--color",
+        action="store_true",
+        help="Enable colored output.",
+    )
+
+    args = parser.parse_args()
+    ignored = sorted(
+        item
+        for items in args.ignore
+        for item in items
+    )
+
+    files: list[_pathlib.Path] = []
+
+    for root in sorted(args.roots):
+        path = _pathlib.Path(root)
+
+        if not path.exists():
+            parser.error(f"root does not exist: {root}")
+
+        if not path.is_dir():
+            parser.error(f"root is not a directory: {root}")
+
+        if args.recursive:
+            paths = path.rglob(args.pattern)
+        else:
+            paths = path.glob(args.pattern)
+
+        for file in paths:
+            if not file.is_file():
+                continue
+
+            if any(
+                ignore in file.parts
+                for ignore in ignored
+            ): continue
+
+            files.append(file)
+
+    for file in sorted(files):
+        spec = _importlib_util.spec_from_file_location(
+            file.stem,
+            file,
+        )
+
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load test module: {file}")
+
+        module = _importlib_util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+    if Lab.print(
+        namespaces=args.namespace or None,
+        failable="ignore" if args.failable else "fail",
+        verbosity=args.verbosity,
+        color=args.color,
+    ): _sys.exit(0)
+
+    _sys.exit(1)
+
+# ------------------------------------------------------------------------------
+# ------------------------------------------------------------------------------