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: Callable[[], None]) -> Callable[[], None]

__call__(
    name: str,
) -> Callable[[Callable[[], None]], Callable[[], None]]

__call__(
    *, name: str
) -> Callable[[Callable[[], None]], Callable[[], None]]

__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.

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`

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():
    ...

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 | str | None = None,
    /,
    *,
    reason: str | None = None,
    name: str | None = None,
    tags: list[str] | None = None,
) -> _Fn | _Decorator

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`

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 | str | None = None,
    /,
    *,
    description: str | None = None,
    name: str | None = None,
    tags: list[str] | None = None,
) -> _Fn | _Decorator

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`

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 | str | None = None,
    /,
    *,
    reason: str | None = None,
    name: str | None = None,
    tags: list[str] | None = None,
) -> _Fn | _Decorator

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_greater_than

to_be_greater_than(n: T) -> MatchResult

Assert the value is greater than n.

Parameters:

Name	Type	Description	Default
`n`	`T`	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: T) -> MatchResult

Assert the value is less than n.

Parameters:

Name	Type	Description	Default
`n`	`T`	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: T) -> MatchResult

Assert the value is greater than or equal to n.

Parameters:

Name	Type	Description	Default
`n`	`T`	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: T) -> MatchResult

Assert the value is less than or equal to n.

Parameters:

Name	Type	Description	Default
`n`	`T`	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: T) -> MatchResult

Assert the value contains item.

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

Parameters:

Name	Type	Description	Default
`item`	`T`	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.

Parameters:

Name	Type	Description	Default
`name`	`str`	The group name shown in test output.	required

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)

API Reference

test decorator

__call__

skip_if

__call__

__call__

__call__

expect assertions

not_ property

to_equal

to_be

to_be_truthy

to_be_falsy

to_be_none

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

`test` decorator

call

call

call

call

`expect` assertions

not_ `property`

`describe` context manager