Behavioral Contracts on S7

In s7contract: Behavioral Contracts and Generative Laws for 'S7'

knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
knitr::read_chunk(
  system.file("examples", "vector-laws.R", package = "s7contract")
)

library(S7)
library(s7contract)

s7contract describes what a consumer needs from an S7 object and tests whether implementations behave as expected. S7 provides class definitions, method registration, and dispatch.

Structural interfaces and explicit traits address the need described in the S7 traits discussion: checking method contracts around existing generics. Go interfaces inform the structural approach; Rust traits inform explicit registrations, defaults, and associated metadata. Here these are runtime R facilities. Checked calls and generative laws extend them from method availability to evidence about behavior.

| Mechanism | Question | |:--|:--| | S7 properties and validators | Is the object's representation valid? | | implements() | Can S7 find the required methods? | | has_trait() | Has this implementation been declared? | | with() / %::% | Do this call's arguments and return value satisfy their specifications? | | check_law() | Does a behavioral claim hold over the generated cases? |

A vector protocol

A windowing function needs length, slicing, and access to values. VectorLike states those requirements. Both double vectors and ReadDepth objects provide the methods; the ReadDepth validator keeps positions and depths aligned.

The consumer uses the protocol without depending on either representation:

assert_implements() checks method availability. Inside with(VectorLike, ...), calls also check the argument and return specifications declared by the interface. For example, its slice operation requires integer indices:

tryCatch(
  with(VectorLike, vec_slice(coverage, "first")),
  error = function(e) conditionMessage(e)
)

Declaring an implementation

Use a trait when a declaration or associated metadata matters to the consumer. Here the declaration attaches measurement units to ReadDepth:

Measured <- new_trait("Measured",
  methods = list(values = trait_method(vec_values)),
  assoc_consts = "UNITS"
)
has_trait(ReadDepth, Measured)

impl_trait(Measured, ReadDepth,
  methods = list(values = function(x) x@depth),
  assoc_consts = list(UNITS = "reads"),
  replace = TRUE
)
has_trait(ReadDepth, Measured)
trait_assoc_const(Measured, ReadDepth, "UNITS")

Testing behavior

Method availability and valid return types leave semantic claims untested. This law checks length against the values used to construct the object:

length_law <- new_law("length matches constructor input",
  generators = list(values = gen_vector(gen_double(-10, 10), max = 6L)),
  holds = function(values) {
    x <- ReadDepth(position = seq_along(values), depth = values)
    with(VectorLike, identical(vec_length(x), base::length(values)))
  }
)
check_law(length_law, tests = 100L, seed = 1L)

The vector law suite runs four laws against both representations and finds a faulty slice method that still satisfies the interface. Its generators preserve valid objects and indices while shrinking.

For generator composition, replay, and tinytest integration, see Generative Laws with tinytest. The Maybe dictionary shows function-valued operations; Testing Stateful S7 Protocols covers sequences of mutations checked against a reference model.

s7contract documentation built on Sept. 10, 2026, 1:09 a.m.