Fixture Conventions

Introduction

Even though one of the objectives of  is to create a common language between the business experts and the development team, there will always be a certain degree of difference between the natural language and the programming language. Hence comes the reason for having fixtures. Fixtures are the glue between the business expert examples and the software being developed. When running the table,  uses a fixture to mediate between the example expressed in the table and the system under test.

Collaboration demands Compromise

The goal of the fixture, is to translate from one language to the other so neither has to compromise their clarity or their design to match the other. The fixture is the compromise. A fixture is any class. It does not have to extend or implement any base class/interface.

The fixture name

The fixture name is found right next to the interpreter specification.

Since a fixture is a Java class, when LivingDoc executes the example, it will try to match the fixture name with a class name.

What about packages?

Usually, Java classes are found inside a package and we can explicitly load a class via the package name.

Readability

The problem with packages and namespace and with the classes naming convention, camel casing and no spaces, is that they makes the example less readable for the business expert.

To help readability, we have the following options:

Aliases

All to offen persons uses a kind of "not really human readable" language when defining names for classes, methods and variables.Those "not really human readable names" can be mapped to a more meaningful name of classes, methods and variables.

A second point is that persons tends to use its native language for defining names which mostly causes conflicts with the convention of coding in english. It is easier to write down the executable table in your native language and map it with english named classes, methods and variables.

You can use the annotation @Alias to specify additional name-definitions.

public class Calculator {
    @Alias({"a number"})
    public double num;
    
    @Alias({"result of square"})
    public double square(){
        return Math.pow(num, 2);
    }
}

Import tables

Import tables are special tables at the beginning of the document.

By using an import table we can remove the package from the fixture name thus improving the readability of the example.

When LivingDoc will search for fixtures in the code, it will look into all the packages specified in the import tables.

You can have more than one package or namespace imported in a document. Just add more lines to the import table.

LivingDoc will search for the fixture in each of these packages until it finds a matching class.

Humanized name

Event without the package, programmatic naming conventions are not the most readable form for the name of the example. This can be arranged by following the camel casing conventions.

Use a free form with space separating each word for the fixture name and make the fixture class use camel casing.

LivingDoc will match the words of the fixture name with the camel cased class name.

The fixture suffix

If you wish to clearly distinguish between your domain classes and the classes that serve as fixture, you can add the suffix Fixture at the end of the fixture classes name.

When writing the example, you can omit the suffix Fixture from the fixture name. This keeps the example closer to the real domain.

public class BankAccountFixture{
...
}

Constructor

A fixture can receive parameters during it's construction. You must have a public constructor that matches the numbers of parameters.

When no parameters are specified in the example, the fixture class must have a public constructor without parameters.

public class BankAccountFixture {
   public BankAccountFixture()
   { ... }
}

public class PokerTableFixture {
   public PokerTableFixture(Ammount ante, Ammount maxBet)
   { ... }
}