API Reference¶

`test` decorator¶

Decorator for marking functions as tests.

Tryke discovers functions decorated with @test (or prefixed with test_) during collection.

Attributes:

Name	Type	Description
`skip`		Skip a test unconditionally.
`todo`		Mark a test as a placeholder.
`xfail`		Mark a test as expected to fail.

Example

from tryke import test

@test
def my_test():
    ...

@test(name="descriptive test name")
def named():
    ...

@test(tags=["slow", "network"])
def tagged():
    ...

call ¶

__call__(fn: _AnyTestFn) -> _AnyTestFn

__call__(name: str) -> _TestDecorator

__call__(
    fn: None = None,
    /,
    *,
    name: str | None = None,
    tags: list[str] | None = None,
) -> _TestDecorator

__call__(fn=None, /, *, name=None, tags=None)

Register a function as a test.

Can be used as a bare decorator (@test) or called with keyword arguments (@test(name="...", tags=[...])) to set metadata. The parametrised form returns a :class:_TestDecorator, which acts as a plain decorator and also exposes .cases(...) so labelled tests can be parametrised in one decoration.

Parameters:

Name	Description	Default
`fn`	The test function (when used as a bare decorator).	`None`
`name`	Optional display name for the test.	`None`
`tags`	Optional list of tags for filtering with `-m`.	`None`

case ¶

case(
    label: str, /, *args: P.args, **kwargs: P.kwargs
) -> _CaseSpec[P]

Build one typed case for a :meth:cases decorator.

The label is an arbitrary string — spaces, math operators, and punctuation are all fine, so "my test" and "2 + 3" both work and survive -k filtering end-to-end.

The *args/**kwargs are typed via PEP 612 _P.args / _P.kwargs so that mypy and pyright can match them against the decorated function's signature inside :meth:cases. ty does not yet enforce this pattern; see the module docstring for :class:_CaseSpec for details.

The keyword names skip, xfail, and todo are reserved for per-case modifiers. When passed, they must be strings and are consumed by the framework — they are not forwarded to the test function.

Example

@test.cases(
    test.case("zero", n=0, expected=0),
    test.case("one",  n=1, expected=1),
    test.case("broken", n=2, expected=999, xfail="bug #42"),
)
def square(n: int, expected: int) -> None:
    expect(n * n).to_equal(expected)

cases ¶

cases(
    *specs: _CaseSpec[P],
) -> Callable[[Callable[P, None]], Callable[P, None]]

cases(
    positional: list[tuple[str, CaseArgs]],
) -> Callable[[_Fn], _Fn]

cases(**kwargs: CaseArgs) -> Callable[[_Fn], _Fn]

cases(
    *positional: object, **kwargs: CaseArgs
) -> Callable[[_Fn], _Fn]

Parametrize a test over multiple named cases.

Pass one :meth:case spec per row. PEP 612 ParamSpec binds the kwargs against the decorated function's signature so typos and mismatched types become static errors under mypy/pyright::

@test.cases(
    test.case("zero",     n=0,  expected=0),
    test.case("one",      n=1,  expected=1),
    test.case("ten",      n=10, expected=100),
)
def square(n: int, expected: int) -> None:
    expect(n * n).to_equal(expected)

ty (as of 0.0.21) does not yet enforce this pattern. Runtime validation still catches label collisions and inconsistent key sets.

Composes with @fixture/Depends() parameters, describe(...) blocks, and @test.skip/@test.xfail.

Raises:

Type	Description
`TypeError`	If no cases are provided, forms are mixed, two cases share a label, or cases disagree on key sets.

skip_if ¶

skip_if(condition: bool, *, reason: str = '') -> _Decorator

Skip a test conditionally, evaluated at import time.

Parameters:

Name	Type	Description	Default
`condition`	`bool`	When `True`, the test is skipped.	required
`reason`	`str`	Optional reason shown in test output.	`''`

Example

import sys

@test.skip_if(sys.platform == "win32", reason="unix only")
def unix_test():
    ...

Bases: _Marker

Skip a test unconditionally.

Can be used as a bare decorator or called with a reason string.

Example

@test.skip
def not_ready():
    ...

@test.skip("waiting on upstream fix")
def with_reason():
    ...

call ¶

__call__(fn_or_reason: _Fn) -> _SkipMarked

__call__(
    fn_or_reason: str | None = ...,
    /,
    *,
    reason: str | None = ...,
    name: str | None = ...,
    tags: list[str] | None = ...,
) -> Callable[[_Fn], _SkipMarked]

__call__(
    fn_or_reason: _Fn | str | None = None,
    /,
    *,
    reason: str | None = None,
    name: str | None = None,
    tags: list[str] | None = None,
) -> object

Mark a test to be skipped.

Parameters:

Name	Type	Description	Default
`fn_or_reason`	`_Fn \| str \| None`	The test function (when used as a bare decorator) or a reason string (when called with parentheses).	`None`
`reason`	`str \| None`	Reason for skipping (alternative to positional string).	`None`
`name`	`str \| None`	Optional test name override.	`None`
`tags`	`list[str] \| None`	Optional list of tags for filtering.	`None`

Bases: _Marker

Mark a test as a placeholder — it will be collected but not executed.

Can be used as a bare decorator or called with a description string.

Example

@test.todo
def future_feature():
    ...

@test.todo("implement caching layer")
def with_description():
    ...

call ¶

__call__(fn_or_desc: _Fn) -> _TodoMarked

__call__(
    fn_or_desc: str | None = ...,
    /,
    *,
    description: str | None = ...,
    name: str | None = ...,
    tags: list[str] | None = ...,
) -> Callable[[_Fn], _TodoMarked]

__call__(
    fn_or_desc: _Fn | str | None = None,
    /,
    *,
    description: str | None = None,
    name: str | None = None,
    tags: list[str] | None = None,
) -> object

Mark a test as a todo placeholder.

Parameters:

Name	Type	Description	Default
`fn_or_desc`	`_Fn \| str \| None`	The test function (when used as a bare decorator) or a description string (when called with parentheses).	`None`
`description`	`str \| None`	Description of what needs to be done (alternative to positional string).	`None`
`name`	`str \| None`	Optional test name override.	`None`
`tags`	`list[str] \| None`	Optional list of tags for filtering.	`None`

Bases: _Marker

Mark a test as expected to fail.

Can be used as a bare decorator or called with a reason string.

Example

@test.xfail
def known_bug():
    ...

@test.xfail("upstream issue #42")
def with_reason():
    ...

call ¶

__call__(fn_or_reason: _Fn) -> _XfailMarked

__call__(
    fn_or_reason: str | None = ...,
    /,
    *,
    reason: str | None = ...,
    name: str | None = ...,
    tags: list[str] | None = ...,
) -> Callable[[_Fn], _XfailMarked]

__call__(
    fn_or_reason: _Fn | str | None = None,
    /,
    *,
    reason: str | None = None,
    name: str | None = None,
    tags: list[str] | None = None,
) -> object

Mark a test as expected to fail.

Parameters:

Name	Type	Description	Default
`fn_or_reason`	`_Fn \| str \| None`	The test function (when used as a bare decorator) or a reason string (when called with parentheses).	`None`
`reason`	`str \| None`	Reason the test is expected to fail (alternative to positional string).	`None`
`name`	`str \| None`	Optional test name override.	`None`
`tags`	`list[str] \| None`	Optional list of tags for filtering.	`None`

`expect` assertions¶

Create an Expectation for expr.

Parameters:

Name	Type	Description	Default
`expr`	`T`	The value to make assertions on.	required
`name`	`str \| None`	Optional label for the assertion (used by the Rust-side discovery to extract assertion labels from source code; unused at runtime).	`None`

Returns:

Type	Description
`Expectation[T]`	An `Expectation` with chainable assertion methods.

Example

>>> from tryke import expect
>>> expect(1 + 1).to_equal(2)
MatchResult(ok)
>>> expect("hello").to_contain("ell")
MatchResult(ok)

Chainable assertion wrapper created by expect.

Every assertion method returns a MatchResult. Use .not_ to negate any assertion.

Example

>>> from tryke import expect
>>> expect(1 + 1).to_equal(2)
MatchResult(ok)
>>> expect(None).not_.to_be_truthy()
MatchResult(ok)

not_ `property` ¶

not_: Expectation[T]

Negate the next assertion.

Example

>>> from tryke import expect
>>> expect(1).not_.to_equal(2)
MatchResult(ok)
>>> expect(None).not_.to_be_truthy()
MatchResult(ok)

to_equal ¶

to_equal(other: T) -> MatchResult

Deep equality check (==).

Parameters:

Name	Type	Description	Default
`other`	`T`	The value to compare against.	required

Example

>>> from tryke import expect
>>> expect(1 + 1).to_equal(2)
MatchResult(ok)
>>> expect([1, 2]).to_equal([1, 2])
MatchResult(ok)

to_be ¶

to_be(other: object) -> MatchResult

Identity check (is).

Parameters:

Name	Type	Description	Default
`other`	`object`	The object to compare identity against.	required

Example

>>> from tryke import expect
>>> sentinel = object()
>>> expect(sentinel).to_be(sentinel)
MatchResult(ok)

to_be_truthy ¶

to_be_truthy() -> MatchResult

Assert the value is truthy (bool(value) is True).

Example

>>> from tryke import expect
>>> expect(1).to_be_truthy()
MatchResult(ok)
>>> expect([1]).to_be_truthy()
MatchResult(ok)

to_be_falsy ¶

to_be_falsy() -> MatchResult

Assert the value is falsy (bool(value) is False).

Example

>>> from tryke import expect
>>> expect(0).to_be_falsy()
MatchResult(ok)
>>> expect("").to_be_falsy()
MatchResult(ok)

to_be_none ¶

to_be_none() -> MatchResult

Assert the value is None.

Example

>>> from tryke import expect
>>> expect(None).to_be_none()
MatchResult(ok)
>>> expect(42).not_.to_be_none()
MatchResult(ok)

to_be_instance_of ¶

to_be_instance_of(cls: type[C]) -> MatchResult

to_be_instance_of(cls: tuple[type, ...]) -> MatchResult

to_be_instance_of(
    cls: type | tuple[type, ...],
) -> MatchResult

Assert the value is an instance of cls.

Accepts either a single class or a tuple of classes, mirroring the built-in [isinstance][]. The single-class form is generic over the expectation's value type, so type checkers flag obvious mismatches like expect(42).to_be_instance_of(str) statically while still allowing downcasts (for example, expect(animal).to_be_instance_of(Dog) when animal: Animal). The tuple form falls back to tuple[type, ...] because requiring every element to match the value's type would reject legitimate "any of these" checks such as expect("hi").to_be_instance_of((bytes, str)).

Parameters:

Name	Type	Description	Default
`cls`	`type \| tuple[type, ...]`	The class (or tuple of classes) to check against.	required

Example

>>> from tryke import expect
>>> expect([1, 2, 3]).to_be_instance_of(list)
MatchResult(ok)
>>> expect("hi").to_be_instance_of((bytes, str))
MatchResult(ok)
>>> expect(42).not_.to_be_instance_of(bool)
MatchResult(ok)

to_be_greater_than ¶

to_be_greater_than(n: C) -> MatchResult

Assert the value is greater than n.

Parameters:

Name	Type	Description	Default
`n`	`C`	The value to compare against.	required

Example

>>> from tryke import expect
>>> expect(5).to_be_greater_than(3)
MatchResult(ok)

to_be_less_than ¶

to_be_less_than(n: C) -> MatchResult

Assert the value is less than n.

Parameters:

Name	Type	Description	Default
`n`	`C`	The value to compare against.	required

Example

>>> from tryke import expect
>>> expect(3).to_be_less_than(5)
MatchResult(ok)

to_be_greater_than_or_equal ¶

to_be_greater_than_or_equal(n: C) -> MatchResult

Assert the value is greater than or equal to n.

Parameters:

Name	Type	Description	Default
`n`	`C`	The value to compare against.	required

Example

>>> from tryke import expect
>>> expect(5).to_be_greater_than_or_equal(5)
MatchResult(ok)

to_be_less_than_or_equal ¶

to_be_less_than_or_equal(n: C) -> MatchResult

Assert the value is less than or equal to n.

Parameters:

Name	Type	Description	Default
`n`	`C`	The value to compare against.	required

Example

>>> from tryke import expect
>>> expect(4).to_be_less_than_or_equal(5)
MatchResult(ok)

to_contain ¶

to_contain(item: object) -> MatchResult

Assert the value contains item.

Works on lists, strings, and any container supporting in.

Parameters:

Name	Type	Description	Default
`item`	`object`	The item to search for.	required

Example

>>> from tryke import expect
>>> expect([1, 2, 3]).to_contain(2)
MatchResult(ok)
>>> expect("hello world").to_contain("world")
MatchResult(ok)

to_have_length ¶

to_have_length(n: int) -> MatchResult

Assert the value has length n.

Parameters:

Name	Type	Description	Default
`n`	`int`	The expected length.	required

Example

>>> from tryke import expect
>>> expect([1, 2, 3]).to_have_length(3)
MatchResult(ok)
>>> expect("hello").to_have_length(5)
MatchResult(ok)

to_match ¶

to_match(pattern: str) -> MatchResult

Regex match against the string representation of the value.

Parameters:

Name	Type	Description	Default
`pattern`	`str`	A regular expression pattern.	required

Example

>>> from tryke import expect
>>> expect("hello world").to_match(r"hello")
MatchResult(ok)
>>> expect("foo123").to_match(r"\d+")
MatchResult(ok)

to_raise ¶

to_raise(
    exc_type: type[BaseException] | None = None,
    *,
    match: str | None = None,
) -> MatchResult

Assert that a callable raises an exception.

Wrap the expression in a lambda.

Parameters:

Name	Type	Description	Default
`exc_type`	`type[BaseException] \| None`	Expected exception type, or `None` for any exception.	`None`
`match`	`str \| None`	Regex pattern to match against the exception message.	`None`

Example

>>> from tryke import expect
>>> expect(lambda: int("abc")).to_raise(ValueError)
MatchResult(ok)
>>> expect(lambda: 1 / 0).to_raise(ZeroDivisionError, match="division")
MatchResult(ok)
>>> expect(lambda: None).not_.to_raise()
MatchResult(ok)

Result of an assertion.

By default assertions are soft — a failing assertion records the failure but does not stop the test. Call .fatal() to opt in to immediate failure.

fatal ¶

fatal() -> None

Stop the test immediately if this assertion failed.

Example

@test
def must_pass():
    expect(config).not_.to_be_none().fatal()  # stops here if None
    expect(config.value).to_equal(42)

`describe` context manager¶

Group tests visually in output.

The describe name is used as a prefix in test names during reporting. The name is inspected by tryke's static discovery, so it must be a string literal when used as with describe("..."):.

Example

from tryke import describe, expect, test

with describe("math"):
    @test
    def addition():
        expect(1 + 1).to_equal(2)

    @test
    def subtraction():
        expect(3 - 1).to_equal(2)

Fixtures¶

A single @fixture decorator handles setup and teardown, with two granularities selected via per=. Scope is determined by position: module top-level applies to all tests in the file; inside a describe() block applies to that group only.

Form	Runs	Scope
`@fixture` (default: `per="test"`)	Before/after every test in scope	Per-test
`@fixture(per="scope")`	Once for all tests in scope	Per-(lexical-)scope

Use yield to split setup and teardown in the same function. See the Writing tests guide for worked examples.

fixture ¶

fixture(fn: F) -> F

fixture(*, per: FixturePer = 'test') -> Callable[[F], F]

fixture(
    fn: _FixtureFn | None = None,
    /,
    *,
    per: FixturePer = "test",
) -> _FixtureFn | Callable[[_FixtureFn], _FixtureFn]

Mark a function as a tryke fixture.

A fixture runs automatically around every test in its lexical scope (module-level fixtures cover all tests in the file; fixtures defined inside with describe(...) cover tests in that describe block).

Use yield to split setup and teardown::

@fixture
def db():
    conn = connect()
    yield conn          # value visible to tests via Depends()
    conn.close()        # teardown runs after each test

Use per="scope" to cache the value across every test in the fixture's lexical scope — the function runs once, and teardown runs after the last test in that scope::

@fixture(per="scope")
def app():
    return TestApp()    # plain return: no teardown

Tests (and other fixtures) consume values with :func:Depends.

`Depends`¶

Depends ¶

Depends(dep: Callable[..., Generator[T, None, None]]) -> T

Depends(dep: Callable[..., AsyncGenerator[T, None]]) -> T

Depends(dep: Callable[..., Awaitable[T]]) -> T

Depends(dep: Callable[..., T]) -> T

Depends(dep: _FixtureFn) -> Any

Declare a dependency on another fixture.

Used in function signatures to request a resolved value, either as a default value or as Annotated metadata::

@fixture(per="scope")
def db() -> Connection:
    return create_connection()

@test
def my_test(conn: Connection = Depends(db)):
    ...

from typing import Annotated

@test
def my_other_test(conn: Annotated[Connection, Depends(db)]):
    ...

Type checkers see Depends(db) as returning Connection. At runtime it returns a :class:_Depends sentinel that the executor resolves before calling the function.

API Reference¶

test decorator¶

__call__ ¶

case ¶

cases ¶

skip_if ¶

__call__ ¶

__call__ ¶

__call__ ¶

expect assertions¶

not_ property ¶

to_equal ¶

to_be ¶

to_be_truthy ¶

to_be_falsy ¶

to_be_none ¶

to_be_instance_of ¶

to_be_greater_than ¶

to_be_less_than ¶

to_be_greater_than_or_equal ¶

to_be_less_than_or_equal ¶

to_contain ¶

to_have_length ¶

to_match ¶

to_raise ¶

fatal ¶

describe context manager¶

Fixtures¶

fixture ¶

Depends¶

Depends ¶

`test` decorator¶

call ¶

call ¶

call ¶

call ¶

`expect` assertions¶

not_ `property` ¶

`describe` context manager¶

`Depends`¶