EDDLiveSlideshow

Example-Driven Development -- bridging tests and documentation

Hello. My name is Oscar Nierstrasz, and I work for feenk. We modernize legacy systems by opening their domain models and making them explainable by extending domain objects with large numbers of custom tools. One of the development techniques we use is called Example-Driven Development, which I'll explain to you now.

Examples as Documentation

Here we see a part of our environment, the Glamorous Toolkit book, a knowledge base of notebook pages with live examples. This page explains the Ludo Game, a programming exercise of a well-known game for children in which tokens move around a board on the roll of a die. Here is an example of an impossible move in the game, where the token cannot move because the roll of the die would move it past the end of the board. We can explore the live example, navigate to the game, and from there to the players, the squares, and even the history of moves. What are we seeing? In each case this is just an object inspector, augmented with custom views to show interesting aspects of the domain objects. The source code of this example is here. It's just returning a move from this game object, which is produced by this test method. Here we see the setup, we perform some actions, and some assertions, and finally — and this is the important part — we return the object under test, which is the example. Note that the setup is created by another test, and so on. In fact, we have a tree of tests, shown in this example maps. Note only can we compose tests, but if a test fails, then its dependent tests will not be run.

- Scroll down to Impossible move - Inspect the example - Replay to here - Inspect the moved of the game - Go back and inspect the source code - Open the code bubble of gameShowingAllMoves5 - Show that it returns an example - Inspect the example - Show the example map - Break an assertion - Run the examples and show which are not run

What's an Example?

An example method is just a test method that happens to return the object being tested. Through this simple change, instead of a passing test simply being green, we get back an object that we can inspect, explore, and reuse for various purposes.

Building on Examples

What can we do with an example? Here we see a partial implementation of a Film Collection object created from an exported CSV of an IMDB collection. The CSV file is an example, as is the JSON data we obtain by parsing the CSV, and the FilmCollection example that wraps the JSON data. Each example is a test case with some assertions, but it also returns the object under test. If we explore the collection, we see that there are more interesting fields that might be nice to see in the Films view. We verify that we can send directors to a film instance, and we update the Films view to show the Directors as well. (Optional) We can also create a new example by extracting the Films of Akira Kurosawa, using that to build a new FilmCollection, and extracting it as an example.

- Browse the collection method. - Show how it is composed. - Inspect the collection. - Inspect a film. - Query its directors. - Update the FilmCollection view with a Directors column. - In the context of FilmCollectionExamples new start from self collection and build up the Kurosawa example - Extract it as an example:

        
FilmCollection new
	data: ((self collection films select: [ :f | f directors = 'Akira Kurosawa' ]) collect: #data)
        
      

Explaining the squarified treemap algorithm

Here's another case study where examples are used to document an algorithm. The squarified Treemap algorithm generates very nicely laid out treemaps using a simple algorithm described in this paper.

A better way to understand the algorithm is using live examples. The picture looks the same, but we can dive into it. At each subdivision step we see whether the algorithm accepts the new node, or if it changes direction to maintain a squarified look.

- Scroll down to the paper - Scroll to the example right after the paper - Dive into the example - Show the Steps figure and the Steps list

Summary -- Why examples?

What are example methods good for?

As we have seen, examples make dependencies between tests explicit by reusing examples as setups for other examples, thus forming a hierarchy of examples.

Best practice in test design supposedly should avoid dependencies between tests, but studies have shown that this practice instead leads to implicit dependencies due to duplicated code in test setups. This in turn leads to cascading failures due to the same setups being repeated in numerous tests. By factoring out the commonalities as examples, the duplication is removed, and cascading failures are avoided.

A further benefit is that examples can be used in live documentation.

Examples also support an exploratory approach to test-driven development, that we call example-driven development, or EDD. The key differences is that, instead of starting from the source code test cases, we start from existing live examples to code new features, and create new, tested examples.

... Custom tools are pervasive

This visualization shows a treemap of packages and classes in the current image.

Blue classes have at least one custom view and green ones have at least one example. This shows that custom tools were heavily used to build the moldable development environment itself.

Here at the top left we see BlElement, the root of the graphical hierarchy.

- Click on the top-left class (BlElement)

... Turning tests into examples

Turning conventional tests into examples is straightforward. Here we have a class that tests the FileLocator utility.

If we run these tests, they are green, but we cannot explore an example unless we break an assertion so the test fails.

We can turn this test into an example easily as follows. We change the method name to leave the old test method as it is. We add a <gtExample> pragma (annotation). And finally we return the fixture. Now we have a green test that returns an example that we can explore.

- Show the class - Edit the test case - Inspect the example

... Examples explorer

Here we see the examples explorer for the entire GT system.

We can dive in, for example, to see the examples maps for all the gtoolkit demos.

- Dive into gtoolkit-demos and see the example maps.

... Examples within GT

Examples are heavily used within GT, both as test cases and to create documentation.

- Run at end during Q&A