Examples as specification

A worked example is a single concrete case, stated as Given/When/Then. “Given a request with no signed-in learner, when GET /my/courses, then it redirects.” There is nothing left to interpret: the case names the input, the action, and the exact result. Where the abstract sentence admitted a 404, a crash, and showing another learner's courses, the example admits one outcome.

That is the inversion Specification by Example makes. The specification is not a paragraph the examples decorate; the examples are the specification, and the prose around them only explains why. For one rung, the set of worked examples is the precise definition of what the rung does — precise because each example is concrete, and complete because the set is chosen to cover the behaviour.

Because a worked example is concrete, it does double duty: it specifies the behaviour and it accepts it. Run the example against the system and one of two things happens — the system produces the stated result, or it does not. There is no third reading to dispute. The example that pinned the meaning is the same artifact the harness runs to prove it.

Pick one of the three /my/courses examples below. The figure renders its Given/When/Then and reports the case it realizes, drawn from the stories of F6.5 · Views with HEExThe HEEx rung that server-renders the catalog and reconciles the learner route into the protected /my/courses.View the spec ladder →. The example is the check: each case is one row the acceptance run evaluates.

On the Portal — the learning platform this course builds — a learner reads their own enrolled courses at the protected route /my/courses; behind it, Portal.Enrollment returns the courses the signed-in learner is enrolled in. The route is protected: a learner cannot see another learner's enrolled courses. The spec does not say “handle the cases.” It states three worked examples, and they are the specification.

The fragment below is the stories text for the /my/courses page, settled at F6.5 · Views with HEExThe HEEx rung that server-renders the catalog and reconciles the learner route into the protected /my/courses.View the spec ladder → — the Given/When/Then for the three cases. It is spec text, not code: the example is what the harness reads.

# /my/courses — "See my courses" (verbatim acceptance, F6.5).
#   Given a signed-in learner with enrollments,
#     when GET /my/courses, then the page renders their own courses.
#   Given a signed-in learner with no enrollments,
#     when GET /my/courses, then it renders an empty state (not an error).
#   Given a request with no signed-in learner,
#     when GET /my/courses, then it redirects — a learner never sees another's courses.

# Each example is one row the acceptance run evaluates.
example_1 = "enrolled learner → their own courses"   # the read case
example_2 = "no enrollments → empty state"           # the empty case
example_3 = "not signed in → redirected"             # the access case
the_spec  = :the_three_examples                 # the examples ARE the specification

A worked example is a concrete Given/When/Then that pins one behaviour; the set of examples is the precise definition of a rung; and because each example is concrete, it doubles as the check the harness runs. The Portal's /my/courses page is specified by three Portal.Enrollment examples, and the acceptance run reads its checks from them. The next dive draws the consequence: when the examples are the checks, the documentation cannot drift from the system.

The sources behind examples-as-specification, and where it connects in the course.