Tests are better than requirements documents because they're more lively. Not only do they describe what the system is to do, they give strong hints about whether it does it. Requirements documents just sit there. The liveliness of tests makes up for the occasional awkwardness of their descriptions. (It's harder to write for two audiences—the human and the test harness—than it is to write for one.)

In a series of talks I gave earlier this year, I described three types of business-facing tests: ones based on business logic, ones based on workflow, and ones based on wireframe mockups of a user interface. I talked about wireframes last, and what I had to say compared poorly to the previous two. Those tests had been simultaneously executable and OK-to-good at communicating. But, when it came to wireframes, the best I could do was draw one on a flipchart and say, "I wish I could lift that off and put it in the computer. The closest I can come is this..."

BAD:   def test_structure_without_audits_or_visits     wireframe_looks_like {       page.has_two_columns.and_all_forms_use_the_session_id.                            and_all_links_use_the_session_id_except_help         page.title.has_id(:patient_display_page).                  and_includes(:current_animal).                  and_includes(:current_client)         page.main_text.has_no_list_named(:visits).                      has_no_list_named(:audits).                      has_a_form_with_action(:want_add_visit_form).                      has_a_form_with_action(:want_add_audit_form).                      has_a_help_popup_named(:patient_display_page).                      and_no_other_actions     }.given_that {       a_user_is_logged_in       an_animal_has_been_selected       the_animal_has_no_visits       animal_treatments_have_never_been_audited       there_is_help_for_page(:patient_display_page)     }   end

That's bad because we have two separate representations, each of whichis lousy for one of the two audiences. I now think I have something better. Here's a wireframe:

It's a drawing createdwith OmniGrafflePro (using a stencil from John Dial). That kind of wireframeis easy for a whole team to talk about, but it's too ambiguous for a testingtool. (How would it know whether a given rectangle is a text box, atext field, or the decoration at the bottom of the window?)Fortunately, Omnigraffle allows you toattach notes to graphics. The yellow tooltip-ish rectangle showsannotations to a text field that remove ambiguity.

Here's a test that uses that wireframe:

The image is just there for human consumption. In real life, I'd want the human to work exclusively on the Graffle document and not think about PNG files at all. Instead, I'd have a script watch for changes to Graffle files and regenerate all the PNG images.

The actual test ignores the image. Instead, it parses the Graffle file ("normal-run.graffle"), hooks the program up to a fake window system that records messages like setStringValue and selectAll, starts the program, waits for it to do all its UI initialization, then compares the state of the windows against what the Graffle document claims. When the tests run, the results look like this:

The error messages could do a better job of pointing to the right control, and it's a shame that the image doesn't appear in the output. (Fit swallows it along with any other HTML tags in the test input. No doubt I could work around that.) However, this output is only for programmers already deep in the code. It doesn't have to be as friendly as output aimed at a wider audience.

I still have two big open questions.

• How much time would it take to make a fake window system that could maintain all the state anyone cares to express in a test? (And what is it that should be expressed in such tests? I'll have more to say on that later, probably.)

• How fragile will these tests be in the face of change? Updating the annotations and the tests has to be a small part of changing the wireframes and the UI code.

The next installment ties this into the Atomic Object style of model/view/controller, as described here (PDF) and in a forthcoming Better Software article. But first, I have to figure out how to parse canvases out of Graffle files. And there's that whole vacation thing.