Project Description

Diffable is an F# library that makes it easy and natural to debug and unit-test values belonging to discriminated union types. It provides functions that generate DOT code representing such values as directed graphs, so that any test failures or unexpected behavior can be quickly debugged.


Discriminated union types play a central role in F# programming; however, they don't play nicely with unit tests. Suppose we are writing a unit test involving a value belonging to a discriminated union type. We likely obtain this value as the result of some functional transformation, and we would like our test to assert that this value satisfies a certain property.

If our test were to fail, and we couldn't figure out why simply by reading through its code, the next logical course of action would be to employ the debugger. We would place a breakpoint in our test and inspect the items involved. In a typical object-oriented unit test, we would be inspecting objects containing localized numeric, boolean, and string data. The debugger works quite well for these tasks. In our case, we instead have to deal with a complex linked structure. Navigating this structure using the debugger is clunky to say the least. A better way to navigate this structure is by viewing a graph image of it. Diffable makes the generation of such images easy and natural.

A common type of unit test involving discriminated unions involves asserting the structural equivalence of two union values. In such cases, Diffable generates an image displaying graphs of both values side-by-side; differing subgraphs are highlighted red. This shows the difference, or "diff", of the two values and is the source of the name Diffable.

Last edited Jun 2, 2011 at 6:46 PM by kevinclancy, version 31