Skip to content

Conformance

rn_forge.web.conformance

Framework-independent HTTP conformance scenarios and redaction rules.

REDACTED = '<redacted>' module-attribute

What :func:redact substitutes for a member that legitimately varies.

VARIABLE_MEMBERS = frozenset({'instance', 'traceId', 'timestamp'}) module-attribute

Body members that differ per request and must not be compared literally.

instance is the request path plus, in practice, an id the driver chose; traceId is generated per request (or per trace, when a caller's traceparent continues one); timestamp is the clock. Everything else in a response body is part of the contract and is compared exactly.

ConformanceArea = Literal['problem', 'concurrency', 'pagination', 'idempotency', 'health', 'auth', 'casing', 'tracing', 'deprecation', 'discovery', 'security', 'cors', 'transfer', 'timestamps', 'operations', 'patch', 'read-mask', 'soft-delete']

Areas covered by the conformance suite.

ConformanceCapability = Literal['session-routes', 'csrf']

An optional binding feature a case needs.

session-routes is a route that authenticates by cookie session only. csrf is the CSRF check on unsafe methods of a session route.

ConformanceCase(id, area, description, request, expect_status, depends_on=(), requires=frozenset(), expect_headers=dict[str, str](), expect_absent_headers=frozenset(), expect_body=dict[str, Any](), expect_header_patterns=dict[str, str](), expect_text=None) dataclass

One wire decision, expressed as a request and the response it must get.

Header names are compared case-insensitively and values exactly. Bodies are compared after :func:redact. depends_on names prerequisite requests in execution order. requires names the optional capabilities a binding must provide for the case to apply to it (see :func:~rn_forge.web.conformance.cases_provided_by).

expect_header_patterns = field(default_factory=(dict[str, str])) class-attribute instance-attribute

Header name → regular expression, matched with re.fullmatch against the header value. Header names are compared case-insensitively, as for :attr:expect_headers. Used where the exact value is not deterministic (a generated span id in traceresponse).

expect_text = None class-attribute instance-attribute

The exact response body, for a case whose body is not JSON (a CSV export). When set, :attr:expect_body is not compared.

RequestSpec(method, path, headers=dict[str, str](), query=dict[str, str | tuple[str, ...]](), body=None) dataclass

The request a driver must issue.

path is relative to whatever base the driver mounts the fixture app at, and always begins with /. A query value that is a tuple is a repeated parameter, one occurrence per item.

case_by_id(case_id)

Return the case with case_id, for resolving depends_on.

Raises:

Type Description
KeyError

No case has that id.

cases_for(area)

Return every case in area, in table order.

cases_provided_by(provides=())

Return every case whose required capabilities a binding provides.

A case with no requires is always returned. A driver parametrizes over this instead of :data:CASES, passing the capabilities its fixture application serves.

Parameters:

Name Type Description Default
provides Collection[ConformanceCapability]

The capabilities the binding provides.

()

Example::

@pytest.mark.parametrize("case", cases_provided_by({"session-routes"}))
def test_conforms(case): ...

redact(body)

Blank the members that legitimately differ per request.

Recurses into nested mappings and lists, so a problem body's extensions and a page's items are covered too. Idempotent: redacting an already-redacted body returns the same thing, which is what makes it safe for a driver to apply without knowing whether the table's expectation was already redacted.

rn_forge.web.conformance.types

The shapes a conformance case is written in, and the redaction rule.

REDACTED = '<redacted>' module-attribute

What :func:redact substitutes for a member that legitimately varies.

VARIABLE_MEMBERS = frozenset({'instance', 'traceId', 'timestamp'}) module-attribute

Body members that differ per request and must not be compared literally.

instance is the request path plus, in practice, an id the driver chose; traceId is generated per request (or per trace, when a caller's traceparent continues one); timestamp is the clock. Everything else in a response body is part of the contract and is compared exactly.

ConformanceArea = Literal['problem', 'concurrency', 'pagination', 'idempotency', 'health', 'auth', 'casing', 'tracing', 'deprecation', 'discovery', 'security', 'cors', 'transfer', 'timestamps', 'operations', 'patch', 'read-mask', 'soft-delete']

Areas covered by the conformance suite.

ConformanceCapability = Literal['session-routes', 'csrf']

An optional binding feature a case needs.

session-routes is a route that authenticates by cookie session only. csrf is the CSRF check on unsafe methods of a session route.

ConformanceCase(id, area, description, request, expect_status, depends_on=(), requires=frozenset(), expect_headers=dict[str, str](), expect_absent_headers=frozenset(), expect_body=dict[str, Any](), expect_header_patterns=dict[str, str](), expect_text=None) dataclass

One wire decision, expressed as a request and the response it must get.

Header names are compared case-insensitively and values exactly. Bodies are compared after :func:redact. depends_on names prerequisite requests in execution order. requires names the optional capabilities a binding must provide for the case to apply to it (see :func:~rn_forge.web.conformance.cases_provided_by).

expect_header_patterns = field(default_factory=(dict[str, str])) class-attribute instance-attribute

Header name → regular expression, matched with re.fullmatch against the header value. Header names are compared case-insensitively, as for :attr:expect_headers. Used where the exact value is not deterministic (a generated span id in traceresponse).

expect_text = None class-attribute instance-attribute

The exact response body, for a case whose body is not JSON (a CSV export). When set, :attr:expect_body is not compared.

RequestSpec(method, path, headers=dict[str, str](), query=dict[str, str | tuple[str, ...]](), body=None) dataclass

The request a driver must issue.

path is relative to whatever base the driver mounts the fixture app at, and always begins with /. A query value that is a tuple is a repeated parameter, one occurrence per item.

redact(body)

Blank the members that legitimately differ per request.

Recurses into nested mappings and lists, so a problem body's extensions and a page's items are covered too. Idempotent: redacting an already-redacted body returns the same thing, which is what makes it safe for a driver to apply without knowing whether the table's expectation was already redacted.

rn_forge.web.conformance.cases

HTTP conformance cases consumed by framework-specific test drivers.

case_by_id(case_id)

Return the case with case_id, for resolving depends_on.

Raises:

Type Description
KeyError

No case has that id.

cases_for(area)

Return every case in area, in table order.

cases_provided_by(provides=())

Return every case whose required capabilities a binding provides.

A case with no requires is always returned. A driver parametrizes over this instead of :data:CASES, passing the capabilities its fixture application serves.

Parameters:

Name Type Description Default
provides Collection[ConformanceCapability]

The capabilities the binding provides.

()

Example::

@pytest.mark.parametrize("case", cases_provided_by({"session-routes"}))
def test_conforms(case): ...