speclike 0.0.0.30

Partial support library for structured testing

speclike

speclike is a pytest helper library designed to define tests in a more structured and expressive way.
It provides a declarative approach for building tests from two complementary perspectives:

• Individual test bodies, written as ordinary methods.
• Externally defined dispatchers and actors, representing scenario-driven or behavior-based tests.

The framework automatically generates executable pytest test functions (test_...) from decorated functions and classes.

---

🧩 Core Concepts

1. Spec and ExSpec Classes

• Spec — the main base class for declarative test specifications.
  It manages auto-generated tests and delegates execution through dispatch() or dispatch_async().
• ExSpec — groups externally defined dispatchers (functions that control test flow outside of the class).

Both are implemented using metaclasses (_SpecMeta, _ExSpecMeta) that synthesize pytest-compatible test functions during class creation.

---

2. Case and Ex Decorators

• Case — marks individual test bodies or actor functions (def _(...):) within a Spec class.
  It can attach pytest marks, parametrize data, or skip tests dynamically.
• Ex — marks dispatcher functions used in ExSpec or top-level definitions.
  Dispatchers define parameter structure using PRM, and connect to actors via @case.ex(dispatcher).

---

3. PRM (Parameter Prefix Rules)

Defines how test parameters behave and interact between dispatcher and actor.

Prefix	Kind	Behavior
_	AO (Actor-Only)	Created by dispatcher, passed to actor (not parametrized)
(none)	AP (Actor-Parametrized)	Parametrized and passed to actor
__	PO (Param-Only)	Parametrized but not passed to actor (used for assertions)

Parameter ordering must follow AO → AP → PO.

PRM validates actor signatures, generates pytest parametrization, and bridges runtime values through _ParamsBridge.

---

4. Dispatcher and Actor

• Dispatcher: a function decorated with @ex that defines test input combinations using PRM.
• Actor: a function named _ decorated with @case.ex(dispatcher) that performs the actual behavior under test.
• The library automatically links each actor to its dispatcher and generates a test_<dispatcher> method that executes the pair.

---

5. Test Generation Workflow

1. The metaclass scans for decorated functions (TargetKind).
2. Each test body or dispatcher/actor pair is converted into a pytest-visible test_... function.
3. Signatures, parametrization, and pytest marks are copied to preserve readability and IDE support.
4. For external specs (ExSpec), tests are created dynamically based on defined dispatchers.

---

6. Highlights

• Strong signature validation for actors against their PRM definitions.
• Automatic propagation of pytest.mark.parametrize and other pytest marks.
• Source location (co_firstlineno) is preserved for accurate traceback references.
• Supports both sync and async test execution paths.

---

Example

from speclike import Spec, PRM

# Example domain object
class Context:
    def compute(self, x: int) -> int:
        return x * 10

# Get decorators
case, ex = Spec.get_decorators()

# Dispatcher (external). Parameters are NOT taken as direct function args.
# Access AP/PO values via the bridge `p`, and call the actor via `p.act(...)`.
@ex.follows(
    [(1, 10), (2, 20), (3, 30)],  # (value, __expected)
    ids=["x1", "x2", "x3"]
)
def check(p = PRM(_ctx=Context, value=int, __expected=int)):
    ctx = Context()                             # AO: create here
    result = p.act(_ctx=ctx, value=p.value)     # call actor with AO/AP
    assert result == p.__expected               # PO: only used in dispatcher

# Spec class with actor method named "_"
class TestCompute(Spec):
    @case.ex(check)
    def _(self, _ctx: Context, value: int) -> int:
        # Actor receives AO/AP only, in the declared order.
        return _ctx.compute(value)

At runtime, this generates:

• test_check — a parametrized pytest function executing the dispatcher.
• act_for_check — an internal bound actor function used by the dispatcher.

---

Labeling Decorator (Case / Ex)

The library provides a hierarchical labeling mechanism applied through decorators such as:

@case.api.input.default
@case.network.timeout
@case.tmp

Each decorator call selects one label from a navigable hierarchy:

Major → Intermediate → Minor

You may specify 0 to 3 labels, and they can be combined simply by chaining attributes. The resulting labels are gathered and stored inside a single pytest mark:

pytest.mark.speclike("api", "input", "default")

The decorator ensures this mark is always attached cleanly to the function’s pytestmark.

---

How the Decorator Behaves

When you write:

@case.api.input.default
def check_something(): ...

the decorator:

1. Collects the labels "api", "input", "default"
2. Normalizes the target’s pytestmark into a list
3. Appends a speclike(...) mark containing those labels

The mark is purely declarative: each decorated function carries structured metadata describing its classification.

---

Current Status of the speclike Marker

A pytest marker named speclike is already defined, but no runtime implementation, filtering logic, or pytest plugin behavior exists yet.

At this stage:

• the marker is attached correctly
• pytest recognizes it as a registered mark
• but it performs no special logic
• filtering such as -m "speclike" is possible, yet argument-based filtering (speclike("api")) is not implemented until the plugin is created

Implementation is planned for future development.

---

Why This Classification Helps

Even without a full plugin, the classification system already provides a strong structural benefit:

• labels consistently encode feature areas, scenarios, or test intent
• larger test suites become easier to navigate and reason about
• test naming and grouping become more predictable
• future tooling or plugins can rely on the embedded structure

Once the speclike implementation is added, these labels will support richer filtering, reporting, and domain-specific test behaviors—while keeping the decorator syntax compact and expressive.

---

Installation

pip

pip install speclike

github

pip install git+https://github.com/minoru-jp/speclike.git

---

Status

This project is in very early development (alpha stage).
APIs and behavior may change without notice.

---

License

MIT License © 2025 minoru_jp