AlignThree is an IDE for writing specifications as tables, and turning them into runnable tests in nine languages. You describe what the software should do — the domain objects, the business rules, the scenarios, each illustrated by a table of examples — and AlignThree generates the test code and the templates for the glue code that connects it to your production classes.
The specification is the source of truth. The tests are generated from it.
Why
It is written before the code, consulted during, and quietly falsified afterwards — and nothing tells you when that happened. The usual answer is to write the examples twice: once in prose for people, once in test code for the machine. Two artefacts, one intent, and no mechanism keeping them honest with each other.
Executable specification collapses that into one artefact. The examples the team agreed on are the test suite, so a specification that has gone stale fails the build rather than sitting there misleading the next reader. AlignThree takes a particular position on how to do that:
Business rules are usually easier to agree on as a table of cases than as sentences. A column heading with six rows underneath makes the boundary cases visible and the missing case conspicuous — exactly the conversation worth having before any code is written.
The spec declares its own types: Entity, Collection,
DataType, Attributes. That declaration is what makes everything
else possible — type checking, generated conversion, cross-file analysis, and a spec that
reads in the domain's own vocabulary.
The types you declared become real classes in your language, and each step becomes a test method. Wiring is done by the generator, at build time, where mistakes are compile errors rather than surprises at 3am.
The format in brief
A .spectable file diffs, merges and reviews like code, because it is a text
file sitting beside everything else. Entities and collections declare the vocabulary;
scenarios read top to bottom as narrative; business rules carry their examples with them.
Specification Shopping Cart
Entity CatalogItem
| Attribute | Type | Default | Notes |
| Name | SimpleText | NoName | |
| Price | Dollar | 1 | |
Collection Catalog
| DataType | Minimum | Maximum | Notes |
| CatalogItem | 0 | 10000000 | Each is unique |
Scenario Add items
Given item collection is : OrderItemCollection
| Name | Price | Quantity | ItemTotal |
When item added : OrderItem Vertical
| Name | Widget |
| Quantity | 2 |
Then item collection is : OrderItemCollection
| Name | Price | Quantity | ItemTotal |
| Widget | $10.00 | 2 | $20.00 |
BusinessRule Total Cart Price
Description How to Apply Discount and Shipping
Examples: CartInput
| TotalItems | Shipping | Discount | Total Price |
| $110 | $5 | $11 | $104 |
| $80 | $5 | $4 | $81 |Why it is useful
The same .spectable drives a Java team and a Go team. Polyglot systems get
one agreed description of behaviour instead of one per stack — Java, C#, Python, Go,
Rust, Swift, JavaScript, TypeScript and C++.
Analyze reports unknown types, duplicate scenario names, =Value references
with no Define, and table rows whose column count does not match the
header — across every file in the solution.
Every generated glue stub ends in a failure, so an unimplemented step is red, never a false green.
Glue methods are created once and only ever appended to; the developer inserts calls to the appropriate production code. Production classes are written only when the type does not already exist anywhere in the folder, and can be used as the real production classes with changes as needed.
Simulate Scenario expands a scenario the way it will actually run, with
Background folded in and =Define references resolved.
Where it comes from
AlignThree is a recombination of three ideas, none of them new, each borrowed for a different reason.
Ward Cunningham's Framework for Integrated Test established that a table of examples is a
better medium for agreeing on a business rule than a paragraph describing it. SpecTable
takes the table wholesale: a BusinessRule with an Examples:
block is FIT's ColumnFixture in a different notation.
Cucumber contributed Given / When / Then: a shape
for describing behaviour over time that non-programmers can read and, more importantly,
collaborate on. SpecTable keeps the keywords and the discipline.
Eric Evans' Domain-Driven Design supplied the model. Entity,
DataType, Collection and DomainTerm are DDD's
terms, used deliberately: the specification is where the ubiquitous language is written
down.
| FIT | SpecTable | |
|---|---|---|
| Format | HTML or wiki pages | plain text — diffs, merges, reviews like code |
| Binding | fixtures written by hand, matched by reflection at run time | test and glue generated at build time |
| Types | none; cells are strings a fixture interprets | declared in the spec, with generated conversion |
| Languages | a fixture per language, written per language | nine targets from one source |
| Narrative | tables only | tables and Given/When/Then scenarios |
Every value is a string until a step definition parses it, and each definition re-does that parsing by hand. SpecTable declares the types once, in the spec, and generates the conversion.
A Cucumber step matches a sentence by pattern; reword it and the binding breaks, sometimes silently. SpecTable derives a method name from the step, so the connection is an identifier the compiler checks.
Gherkin's data tables are attachments to a sentence. In SpecTable a step names the
attribute set describing its table — When item added : OrderItem — so the
table's shape is declared and checked, not inferred at run time.
SpecTable's declarations are project-wide, which is what makes Go to Definition, Find All References, rename and cross-file analysis possible at all.
.feature file aloud in a meeting. SpecTable's tables ask a little more of
the reader in exchange for being checkable — a real trade, and the wrong one if your audience
will not read a table.
What gets generated
common/ is rewritten on every build; never edit it. Glue and production code
are yours and are never overwritten — glue methods are appended to, and a production stub
is written only when that type does not already exist anywhere in the folder.
<outputDirectory>/
common/ generated value classes — XString, XTyped, and an index
<Spec>_Test the tests
<Spec>_glue the glue — where you write code
production/ stubs for your production classesDocumentation
To a working specification without deciding anything you would have to undo later.
Start here →Using the IDE: the workspace, writing specifications, generating code, Analyze, sharing work.
Read the guide →The language reference — every element, the grammar, and the semantics.
Reference →What a .specconfig is, every field, and where the output goes.
Sharing through GitHub — and why, on most machines, there is nothing to configure.
Set up sharing →Everything in one place, with a short description of what each document covers.
Browse →