Last update, 14.06.2009. Read more on the News.

About

BDoc documents behaviour specified by unit tests. In its easiest form it is like TestDox, creating simple documentation from the method names in JUnit test cases.

In its more advanced form it can produce a quality report, describing userstories and behaviour implemented by the code. This will give extra value to the developers and testers of the team. It will contribute on giving attention to unittesting, test-driven development and behaviour-driven development. By showing the report to the business people and testers the developers will get feedback on how they describe the domain, which contributes to code (and developers) being in sync with the UbiquitousLanguage of the project.

A quality report giving value can be achieved by adding some thought to how a test is named, writing it as sentence describing behaviour. DanNorh.net gives an excellent article on this topic. If user stories is used on the project it is also possible to reference the user story from the test, adding even more value to the end report.

BDoc will structure a report depending on specified behaviour and userstories. The following types of behaviour are supported:

• Scenario - Behaviour that gives meaning outside of a specific class
• Specification - Behaviour focused on one class
• Statement - Untyped behaviour
• Test tables - Tables with input values and expected output values

BDoc also comes with its own diff-report, which makes it easy to see changes. This could be usefull if tracing changes in behaviour is an issue for testers or business people. But most of all the diff-report is a tool for the developer, which makes it easy to read the behaviour that is updated, and doing QA of the behaviour added or deleted. Hooking the main-report and the diff-report to continuous integration is also an option, making distribution of updated reports an easy task.

Read more about BDoc on TheServerSide.com

Example

The code below describes and tests the behaviour of an ExecutiveOfficer. The testcase uses a Reference to a Story, one scenario, one statement and a few specifications. Running BDoc on this code, together with testcases for Task and TaskList, will produce this REPORT

package com.googlecode.bdoc.examples.taskhandling;

import static org.junit.Assert.assertTrue;

import org.junit.Before;
import org.junit.Test;

@Ref(Story.TASKTRACKING)
public class TestExecutiveOfficer {

	private ExecutiveOfficer bob;

	@Before
	public void setupExecutiveOfficer() {
		bob = new ExecutiveOfficer("Bob");
	}

	@Test // Scenario - given[]When[]Then[]
	public void givenAnExecutiveOfficerWithNoTasksAssignedWhenTheOfficerCreatesANewTaskThenEnsureItIsAssignedToTheOfficer() {
		Task task = bob.createTask("Register salesorder");
		assertTrue(bob.isAssignedTo(task));
	}

	@Test // Specification - should[]
	public void shouldBeAbleToStartATaskAssigned() {
		Task task = bob.createTask("Register salesorder");
		bob.start(task);
		assertTrue(task.isInProgress());
	}

	@Test // Statement - []
	public void aNewExecutiveOfficerShouldNotHaveAnyTasksInHisOrHerTaskList() {
		assertTrue(bob.getTaskList().getList().isEmpty());
	}

	@Test(expected = IllegalArgumentException.class) 
	public void shouldNotBeAbleToStartATaskAssignedToOthers() {
		ExecutiveOfficer sally = new ExecutiveOfficer("sally");
		Task task = sally.createTask("Pay salary");
		bob.start(task);
	}

	@Test(expected = IllegalStateException.class)
	public void shouldOnlyBeAbleToStartOneTaskAtTheTime() {
		Task task1 = bob.createTask("Register salesorder");
		bob.start(task1);

		Task task2 = bob.createTask("Register payment");
		bob.start(task2);
	}
}