select#

Selection Phase for Canary Test Execution#

This module implements the election stage of the Canary test lifecycle. Selection applies a sequence of rules to mask (exclude) test specifications based on resource availability, user-defined criteria, and dependency relationships. The result of selection is a stable, filtered list of ResolvedSpec instances ready for execution.

Overview#

The selection flow is:

selector = Selector(specs, workspace, rules) final_specs = canary_select(selector)

Selection performs three primary actions:

  1. Rule Evaluation — Each ResolvedSpec is evaluated against each Rule. If any rule fails, the spec receives a Mask with the reason.

  2. Mask Propagation — If a spec is masked, all specs depending on it are also masked.

ResolvedSpec instances.

Caching and Snapshots#

Selection results can be cached using SelectorSnapshot. A snapshot includes:

  • The stable hash of the input spec set

  • A mapping of masked spec IDs to their reasons

  • The serialized rule set

  • A timestamp

Snapshots allow callers to determine whether cached selections remain valid after a workspace changes.

Plugin Integration#

Plugins participate in the selection lifecycle via:

  • canary_selectstart — Mutate or inspect the Selector before execution.

  • canary_select_modifyitems — Adjust masked/unmasked items after rules run.

  • canary_select_report — Emit reporting data after selection.

This keeps the selection engine deterministic while allowing flexible extensibility.

class SelectorSnapshot(spec_set_id: str, masked: dict[str, str], rules: list[str], created_on: str)#

Bases: object

Serializable snapshot of a completed selection run.

SelectorSnapshot represents the minimal state required to determine whether a cached selection result is still valid and, if so, to reconstruct the selected tests without fully re-running all rules.

spec_set_id: str#
masked: dict[str, str]#
rules: list[str]#
created_on: str#
serialize() → str#
static schema() → Schema#
classmethod reconstruct(serialized: str) → SelectorSnapshot#
is_compatible_with_specs(specs: list[ResolvedSpec]) → bool#

Return True if the snapshot matches the current spec set.

apply(specs: list[ResolvedSpec]) → None#
class Selector(specs: list[ResolvedSpec], workspace: Path, rules: Iterable[Rule] = ())#

Bases: object

Apply rule-based masking to a set of resolved specifications.

Selector is responsible for evaluating rules against each ResolvedSpec, propagating masks through dependency graphs, and finalizing the resulting test specifications.

Parameters:

  • specs – The list of ResolvedSpec objects to select from.

  • rules – Optional iterable of Rule instances.

specs#

The input list of resolved specs.

rules#

The rule sequence applied during selection.

rules: list[Rule]#
masked: set[str]#
add_rule(rule: Rule) → None#
iter_rules() → Generator[Rule, None, None]#
run() → list[ResolvedSpec]#
propagate() → None#
static spec_set_id(specs: list[ResolvedSpec]) → str#
snapshot() → SelectorSnapshot#
classmethod from_snapshot(specs: list[ResolvedSpec], workspace: Path, snapshot: SelectorSnapshot) → Selector#
static setup_parser(parser: Parser, tagged: str = 'required') → None#
class RuntimeSelector(cases: list[TestCase], workspace: Path, rules: Iterable[RuntimeRule] = ())#

Bases: object

Apply rule-based masking to a set of test cases.

rules: list[RuntimeRule]#
masked: set[str]#
add_rule(rule: RuntimeRule) → None#
iter_rules() → Generator[RuntimeRule, None, None]#
run() → None#
propagate() → None#
canary_addoption(parser: Parser) → None#

Register Selection-related command-line options.

This hook adds --show-excluded-tests to the console reporting group for the canary run command.

Parameters:

parser – The argument parser used to register command-line flags.

canary_select_report(selector: Selector) → None#

Emit a report summarizing which specs were selected or excluded.

Reporting includes the count of selected and excluded tests, grouped by mask reason. If --show-excluded-tests was provided, individual spec names are also emitted.

Parameters:

selector – The Selector instance whose results are being reported.

canary_rtselect_report(selector: RuntimeSelector) → None#