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