Exploration Through Example

Example-driven development, Agile testing, context-driven testing, Agile programming, Ruby, and other things of interest to Brian Marick
191.8 167.2 186.2 183.6 184.0 183.2 184.6

Thu, 01 Jan 2004

Tests as documentation for later readers: an example

I think it's hard for people to understand what I mean when I talk about product-level tests driving coding. It's easy to think that the actual executable tests are the only thing the programmer uses to understand the problem to be solved. That's not true. There's conversation with other people. And there are annotations attached to the tests. Thinking about what it would mean for tests alone to drive coding gives little or no understanding of what I really mean.

Conversation is hard to show in a blog, but I can show what I mean by annotations. What follows are the actual tests I used to add a new type of fixture to FIT (a table-driven testing framework). Twelve people will soon be using this fixture, and I wanted these tests also to help them understand how to use it. But what I mainly used them for was guiding me, step-by-step, through the coding.

The example is as I wrote it, except that I removed the egregious glop that Word insists on putting in HTML files. Looking back on it from a few days' remove, it has obvious weaknesses when you approach it expecting user documentation. But I think flaws are typical, so I will not fix them just to save myself embarrassment.

It's likely the tests will be confusing to people who don't know FIT. One of the characteristics of Agile documentation, I think, is that it does not attempt to educate the reader into the tacit and explicit knowledge that can be had in other ways. In this case, the other way is experience with FIT (which, I think, usually means reading the FIT code to answer questions). More commonly, the knowledge is had by being part of the development team.

This is an odd case, because what follows uses a tool to test an addition to itself. The Java code that lies behind the tables may help, so that's included afterwards.

NOTE: If you're attending the MFA for software trial run - this means you, Chad - don't read these tests. I need fresh reactions for my first lecture.

 

These tests are about the StepFixture

fit.StepFixture

A StepFixture alone is not useful. Instead, it's subclassed. We'll use StepFixtureTestFixture.

fit.StepFixtureTestFixture

Steps are designated by the first cell of a column. Arguments are in following cells. check is a special name: it calls the no-argument method in the second column and compares the result to the value in the third column.

fit.StepFixtureTestFixture

   

check

stringIsEmpty

true

add

one string arg

 

check

stringIsEmpty

false

check

currentString

1:/one string arg/

add

arg 1

arg 2

check

currentString

1:/one string arg/2:/arg 1/+/arg 2/

add

   

check

currentString

1:/one string arg/2:/arg 1/+/arg 2/3://

State is maintained across tables, but you can reset it.

fit.StepFixtureTestFixture

   

check

currentString

1:/one string arg/2:/arg 1/+/arg 2/3://

restart

   

check

stringIsEmpty

true

Because StudlyCaps style is not fit for humans, check arguments and other steps can be written in a more friendly style.

fit.StepFixtureTestFixture

   

check

string is empty

true

add a string

a string

 

check

current string

1:/a string/

Arguments can be any type that FIT knows how to convert.

fit.StepFixtureTestFixture

   

set a date

January 19, 1960

 

check

date

January 19, 1960

set an integer

45

 

check

integer

45

You shouldn't use two methods with the same name and same number of arguments. The results are undefined, but doubtless not good.

A check step can also take extra arguments. The last cell remains the expected value, but cells before it are passed to the method.

fit.StepFixtureTestFixture

       

set a date

February 9, 1906

     

check

date

day

9

 

check

plus

1

20

21


package fit;

import java.util.Date;
import java.util.GregorianCalendar;
import java.util.Calendar;

public class StepFixtureTestFixture extends StepFixture {

    private String result = "";
    private int count = 0;


    private String countPrefix() {
        count++;
        return count+":";
    }

    private String delimited(String s) {
        return "/"+s+"/";
    }

    public void add() {
        result += countPrefix() + delimited("");
    }

    public void add(String s) {
        result += countPrefix() + delimited(s);
    }

    public void add(String s, String s2) {
        result += countPrefix() + delimited(s) + "+" + delimited(s2);
    }

    public void addAString(String s) {
        add(s);
    }

    public String currentString() {
        return result;
    }

    public boolean stringIsEmpty() {
        return currentString().equals("");
    }

    private Date someRandomDate;
    private int someRandomInteger;

    public Date date() {
        return someRandomDate;
    }

    public int date(String day) {
        GregorianCalendar cal = new GregorianCalendar();
        cal.setTime(someRandomDate);
        return cal.get(Calendar.DAY_OF_MONTH);
    }

    public int integer() {
        return someRandomInteger;
    }

    public int plus(int first, int second) {
        return first+second;
    }

    public void setADate(Date date) {
        someRandomDate = date;
    }

    public void setAnInteger(int integer) {
        someRandomInteger = integer;
    }
}


## Posted at 18:14 in category /testing [permalink] [top]

About Brian Marick
I consult mainly on Agile software development, with a special focus on how testing fits in.

Contact me here: marick@exampler.com.

 

Syndication

 

Agile Testing Directions
Introduction
Tests and examples
Technology-facing programmer support
Business-facing team support
Business-facing product critiques
Technology-facing product critiques
Testers on agile projects
Postscript

Permalink to this list

 

Working your way out of the automated GUI testing tarpit
  1. Three ways of writing the same test
  2. A test should deduce its setup path
  3. Convert the suite one failure at a time
  4. You should be able to get to any page in one step
  5. Extract fast tests about single pages
  6. Link checking without clicking on links
  7. Workflow tests remain GUI tests
Permalink to this list

 

Design-Driven Test-Driven Design
Creating a test
Making it (barely) run
Views and presenters appear
Hooking up the real GUI

 

Popular Articles
A roadmap for testing on an agile project: When consulting on testing in Agile projects, I like to call this plan "what I'm biased toward."

Tacit knowledge: Experts often have no theory of their work. They simply perform skillfully.

Process and personality: Every article on methodology implicitly begins "Let's talk about me."

 

Related Weblogs

Wayne Allen
James Bach
Laurent Bossavit
William Caputo
Mike Clark
Rachel Davies
Esther Derby
Michael Feathers
Developer Testing
Chad Fowler
Martin Fowler
Alan Francis
Elisabeth Hendrickson
Grig Gheorghiu
Andy Hunt
Ben Hyde
Ron Jeffries
Jonathan Kohl
Dave Liebreich
Jeff Patton
Bret Pettichord
Hiring Johanna Rothman
Managing Johanna Rothman
Kevin Rutherford
Christian Sepulveda
James Shore
Jeff Sutherland
Pragmatic Dave Thomas
Glenn Vanderburg
Greg Vaughn
Eugene Wallingford
Jim Weirich

 

Where to Find Me


Software Practice Advancement

 

Archives
All of 2006
All of 2005
All of 2004
All of 2003

 

Join!

Agile Alliance Logo