Example Object

How do you organize examples for testing and documentation?

Concrete examples are need for many purposes, such as documentation, testing, and exploration. Examples can be complex to set up.Unit tests consume examples, but they are only accessible if a test fails.

Wrap examples as (instance) methods that optionally evaluate some tests (assertions), and return the example instance. Each example may also use one or more examples as the initial setup for the new example.

To start, you need a modified unit testing framework in which tests return the exercised fixture, namely, an example. In GT, you create an Example by defining a parameterless method that has a <gtExample> pragma, and returns an object. (A similar framework for Java is JExample.)

[…]

Examples can be embedded in the notebook pages of a Project Diary. Examples can produce a Moldable Object for moldable development.

(Consequences) Examples can be run just like classical unit tests. When an example fails, its dependent examples do not need to be run. When an example succeeds, it can be inspected, used as a moldable object to start coding, or embedded as a live example snippet within a notebook page to illustrate some point. (The example snippets above illustrate this.) When you are searching for usages of an API, not only do you find examples that illustrate the usage, but by running the example you obtain a live instance that you can explore.