Python API reference

The objects below are exported from testenix and form the public pre-1.0 API. Pre-1.0 releases may still make documented breaking changes.

Authoring

testenix.test(function: Callable[[P], R], /) → Callable[[P], R][source]
testenix.test(description: str | None = None, /, *, tags: Iterable[str] | str = (), timeout: float | None = None) → Callable[[Callable[[P], R]], Callable[[P], R]]

Mark a function as a native Testenix test.

Supported forms are @test, @test(), @test("description") and @test(description="description", tags={...}, timeout=...).

Parameters:

  • function_or_description (Callable[[...], Any] | str | None)

  • description (str | None)

  • tags (Iterable[str] | str)

  • timeout (float | None)

Return type:

Callable[[…], Any]

testenix.fixture(function: Callable[[P], R], /) → Callable[[P], R][source]
testenix.fixture(function: None = None, /, *, scope: Scope | str = Scope.TEST, name: str | None = None, autouse: bool = False) → Callable[[Callable[[P], R]], Callable[[P], R]]

Declare a dependency provider with test, module or session lifetime.

Parameters:

  • function (Callable[[...], Any] | None)

  • scope (Scope | str)

  • name (str | None)

  • autouse (bool)

Return type:

Callable[[…], Any]

testenix.case(values=None, /, *, id=None, **parameters)[source]

Attach one concrete parameter case.

Examples:

@case(user="alice", expected=True)
@case("anonymous", user=None, expected=False)
@case({"id": 42}, id="record-42")
Parameters:

  • values (Mapping[str, Any] | str | None)

  • id (str | None)

  • parameters (Any)

Return type:

CaseDefinition

testenix.cases(*definitions, ids=None, **dimensions)[source]

Attach several cases, either explicitly or as a Cartesian product.

@cases({"x": 1}, {"x": 2}) declares explicit mappings, while @cases(role=["admin", "editor"], active=[True, False]) creates the Cartesian product of the supplied dimensions.

Parameters:

  • definitions (CaseDefinition | Mapping[str, Any])

  • ids (Sequence[str] | None)

  • dimensions (Iterable[Any])

Return type:

Callable[[F], F]

skip

@skip(reason_or_function=None, /, *, reason=None, when=True)

Mark a test as skipped. It can be used as @skip, @skip("reason"), or with a conditional when=....

xfail

@xfail(reason_or_function=None, /, *, reason=None, when=True)

Mark a test as expected to fail. An unexpected pass becomes the gating XPASS status.

class testenix.CaseDefinition(parameters, id=None)[source]

One concrete parameter mapping attached to a test function.

Parameters:

  • parameters (Mapping[str, Any])

  • id (str | None)

Discovery and execution

testenix.discover(paths='.')[source]

Discover native tests and fixtures below one or more paths.

Directories are searched recursively for test_*.py. An explicitly supplied Python file may have any name, which is useful for focused runs. Inside a module, test_* functions and functions decorated with @test (or parameterized with @case(s)) are collected.

Parameters:

paths (str | Path | Iterable[str | Path])

Return type:

CollectionResult

testenix.run(paths=None, config=None, *, event_sink=None, sharding_policy=None, trusted_manifest=None)[source]

Discover and execute a native Testenix suite.

The coordinator is the only component that decides final outcomes. Workers return immutable attempts, which are emitted to a versioned event stream and reduced after execution.

Parameters:

  • paths (Sequence[str] | str | None)

  • config (TestenixConfig | None)

  • event_sink (EventSink | None)

  • sharding_policy (ShardingPolicy | None)

  • trusted_manifest (TrustedCollectionManifest | None)

Return type:

RunResult

async testenix.run_async(paths=None, config=None, *, event_sink=None, sharding_policy=None, trusted_manifest=None)[source]

Cancellable embedding facade around the process-oriented coordinator.

Parameters:

  • paths (Sequence[str] | str | None)

  • config (TestenixConfig | None)

  • event_sink (EventSink | None)

  • sharding_policy (ShardingPolicy | None)

  • trusted_manifest (TrustedCollectionManifest | None)

Return type:

RunResult

class testenix.TestenixConfig(paths=('tests',), workers='auto', retries=0, timeout=None, tags=(), json_path=None, junit_path=None, history_path=PosixPath('.testenix/history.sqlite3'), shard_modules=False, manifest_path=None)[source]

Validated execution and reporting settings.

Paths are kept relative to the process working directory. This mirrors normal command-line path handling and makes a config object safe to pass to a worker process without retaining hidden project state.

Parameters:

  • paths (tuple[str, ...])

  • workers (int | Literal['auto'])

  • retries (int)

  • timeout (float | None)

  • tags (tuple[str, ...])

  • json_path (Path | None)

  • junit_path (Path | None)

  • history_path (Path | None)

  • shard_modules (bool)

  • manifest_path (Path | None)

with_overrides(**values)[source]

Return a validated copy containing command-line overrides.

Parameters:

values (Any)

Return type:

TestenixConfig

property resolved_workers: int

Pre-discovery worker capacity retained for compatibility.

Native execution should prefer resolve_workers(), which can see the scheduler’s real module/timeout execution units. Explicit integer configuration has identical behavior through both APIs.

resolve_workers(selected_specs, durations, *, spawn_method='spawn', shardable_paths=frozenset({}))[source]

Resolve an adaptive count after discovery and history lookup.

Parameters:

  • selected_specs (Sequence[TestSpec])

  • durations (Mapping[str, float])

  • spawn_method (SpawnMethod)

  • shardable_paths (AbstractSet[str])

Return type:

int

Result contracts

class testenix.RunResult(run_id: 'str', tests: 'tuple[TestResult, ...]', collection_issues: 'tuple[CollectionIssue, ...]', started_at: 'float', finished_at: 'float', workers_used: 'int | None' = None, shardable_paths: 'tuple[str, ...]' = ())[source]
Parameters:

  • run_id (str)

  • tests (tuple[TestResult, ...])

  • collection_issues (tuple[CollectionIssue, ...])

  • started_at (float)

  • finished_at (float)

  • workers_used (int | None)

  • shardable_paths (tuple[str, ...])

class testenix.TestResult(test: 'TestSpec', status: 'Status', attempts: 'tuple[AttemptResult, ...]', duration: 'float')[source]
Parameters:

  • test (TestSpec)

  • status (Status)

  • attempts (tuple[AttemptResult, ...])

  • duration (float)

class testenix.TestSpec(id, path, module_name, function_name, display_name, parameters=<factory>, case_id=None, tags=<factory>, skip_reason=None, xfail_reason=None, timeout=None, source_line=None)[source]

Serializable description of one concrete test case.

Parameters:

  • id (str)

  • path (str)

  • module_name (str)

  • function_name (str)

  • display_name (str)

  • parameters (dict[str, Any])

  • case_id (str | None)

  • tags (frozenset[str])

  • skip_reason (str | None)

  • xfail_reason (str | None)

  • timeout (float | None)

  • source_line (int | None)

class testenix.CollectionResult(items, registry, issues=())[source]

Complete collection output, including non-fatal authoring issues.

Parameters:

  • items (tuple[CollectedTest, ...])

  • registry (FixtureRegistry)

  • issues (tuple[CollectionIssue, ...])

class testenix.Status(value)[source]

A lossless outcome vocabulary for phases, attempts, and tests.

class testenix.Scope(value)[source]

Lifetime of a fixture instance.

Migration

The programmatic API follows the same copy-only transaction as testenix migrate. project_root defaults to the current directory. Prefer dry_run=True before a validating or publishing call.

from pathlib import Path

from testenix import MigrationOptions, migrate

report = migrate(
    MigrationOptions(
        framework="auto",
        sources=(Path("tests"),),
        output=Path("tests_testenix"),
        check_only=True,
    )
)
assert report.originals_modified is False
testenix.migrate(options)[source]

Analyze, validate, and optionally publish a native Testenix copy.

No branch of this function writes to a source path. A destination is only published by a no-overwrite rename after the source fingerprints have been checked for concurrent changes.

Parameters:

options (MigrationOptions)

Return type:

MigrationReport

class testenix.MigrationOptions(framework, sources, output=PosixPath('testenix_migrated'), workers='auto', validation_timeout=300.0, dry_run=False, check_only=False, project_root=None)[source]

Validated input for migrate().

Parameters:

  • framework (Literal['auto', 'pytest', 'unittest'])

  • sources (tuple[Path, ...])

  • output (Path)

  • workers (int | Literal['auto'])

  • validation_timeout (float)

  • dry_run (bool)

  • check_only (bool)

  • project_root (Path | None)

class testenix.MigrationReport(status, mode, framework, project_root, sources, output, source_hashes, generated_files, mappings, diagnostics, baseline, native_serial, native_parallel, originals_modified, published, message, started_at, finished_at)[source]

Complete audit record for a migration attempt.

Parameters:

  • status (MigrationStatus)

  • mode (str)

  • framework (str)

  • project_root (str)

  • sources (tuple[str, ...])

  • output (str)

  • source_hashes (Mapping[str, str])

  • generated_files (tuple[str, ...])

  • mappings (tuple[TestMapping, ...])

  • diagnostics (tuple[MigrationDiagnostic, ...])

  • baseline (ValidationSummary | None)

  • native_serial (ValidationSummary | None)

  • native_parallel (ValidationSummary | None)

  • originals_modified (bool)

  • published (bool)

  • message (str)

  • started_at (float)

  • finished_at (float)

class testenix.MigrationStatus(value)[source]

Terminal state of one migration transaction.

class testenix.ValidationSummary(runner, tests, passed, failed, errors, skipped, xfailed, xpassed, exit_code, duration, timed_out=False, detail=None, outcomes=<factory>)[source]

Framework-neutral outcome counts from one isolated validation run.

Parameters:

  • runner (str)

  • tests (int)

  • passed (int)

  • failed (int)

  • errors (int)

  • skipped (int)

  • xfailed (int)

  • xpassed (int)

  • exit_code (int)

  • duration (float)

  • timed_out (bool)

  • detail (str | None)

  • outcomes (Mapping[str, str])

Events

class testenix.Event(event_id, run_id, event_type, timestamp, sequence, schema_version=1, test_id=None, attempt=None, worker_id=None, payload=<factory>)[source]

Append-only fact emitted while a run is executing.

Parameters:

  • event_id (str)

  • run_id (str)

  • event_type (EventType)

  • timestamp (float)

  • sequence (int)

  • schema_version (int)

  • test_id (str | None)

  • attempt (int | None)

  • worker_id (str | None)

  • payload (dict[str, Any])

class testenix.EventSink(*args, **kwargs)[source]

Minimal sink contract used by runners, workers and adapters.

emit(event)[source]

Persist one immutable event and return it.

Parameters:

event (Event)

Return type:

Event