FancordionUser Guide
Overview
Fancordion
transforms your boring unit tests into beautiful specification documents! It is similar to Cucumber but focuses on readability and presentation.
Fancordion
embeds test results directly into your test documentation, giving it real meaning.
Features:
- Pretty - creates beautiful HTML output.
- Simple - run Fancordion tests with fant, just like a unit test!
- Linkable - create organised and hierarchical index pages with the
run
command. - Extensible - write your own commands with ease.
- Skinnable - Customise your HTML reports as you see fit.
For an example of Fancordion results, see the output from the Java Concordion framework.
Install
Install Fancordion
with the Fantom Repository Manager ( fanr ):
C:\> fanr install -r http://repo.status302.com/fanr/ afFancordion
To use in a Fantom project, add a dependency to build.fan
:
depends = ["sys 1.0", ..., "afFancordion 0.0+"]
Documentation
Full API & fandocs are available on the Status302 repository.
Quick Start
1). Create a text file called HelloWorldFixture.fan
using afFancordion ** My First Fixture ** ################ ** ** This is a simple Fancordion fixture that verifies that the method ** 'greeting()' returns 'Hello World!'. ** ** Example ** ------- ** Fancordion says, [Hello World!]`verify:eq(greeting)` ** class HelloWorldFixture : FixtureTest { Str greeting() { "Hello World!" } }
2). Run HelloWorldFixture.fan
as a Fantom test script ( fant ) from the command prompt:
C:\> fant HelloWorldFixture.fan -- Run: HelloWorldFixture_0::HelloWorldFixture.testFancordionFixture... Pass: HelloWorldFixture_0::HelloWorldFixture.testFancordionFixture [0] [info] [afFancordion] file:/C:/temp/fancordion/HelloWorldFixture.html Time: 691ms *** *** All tests passed! [1 tests, 1 methods, 1 verifies] ***
3). View the generated fixture result file:
The green highlight means the test passed.
Try changing Hello World!
to something else and re-run the test to watch it fail.
Then have greeting()
throw an Err... See the stacktrace embedded in the result!
Terminology
An Acceptance Test is a standard Fantom Test that has been enhanced to verify real user requirements.
The Fixture is the code part of the acceptance test that does the actual work.
Specification refers to the documentation part of the acceptance test.
Commands are special links in the specification that drive the test, specifying input and verifying output.
Usage
Any Fantom class annotated with the @Fixture facet can be run as a Fancordion fixture. Just pass it into FancordionRunner.runFixture()
:
using afFancordion ** My first Fancordion fixture. @Fixture class MyFixture { ... } fixture := MyFixture() runner := FancordionRunner() runner.runFixture(fixture)
FancordionRunner is designed to be subclassed and has several methods, or hooks, that change it's behaviour:
suiteSetup()
is only ever called once no matter how many fixtures are run, orFancordionRunners
created.suiteTearDown()
again is only ever called the once (currently in an Env shutdown hook).fixtureSetup()
is called before every fixture.fixtureTearDown()
is called after every fixture.skinType
&gimmeSomeSkin()
determine & create an instance of theFancordionSkin
class used to render the result HTML. You could, for instance, change this to use a Bootstrap skin.outputDir
is where the result files are saved.commands
is a map of all the Commands made available to the test. To extend Fancordion, simply add your own Command implementation to the map! (Super easy!)
To help you bridge the gap between Fancordion and standard Fantom tests, Fancordion ships with FixtureTest. This handy class lets you run any Fixture as a Fantom Test.
To use a specific FancordionRunner
in your tests, override fancordionRunner()
to return desired instance. Even though all your tests will extend FixtureTest
, the fancordionRunner()
method will only be called once. This means you can run a single test with fant, or all of them, and they will still only use the same runner instance.
Specifications
Specifications are documents written in Fantom's own Fandoc format, similar to Markdown and Almost Plain Text.
By marking text in the specification as links, you turn them into commands. Your specification can now be thought of as a simple script.
When you run the specification script, the Fandoc is converted into HTML and the commands executed as they are encountered. The commands generate HTML markup to show whether they passed or failed.
By default the specification is assumed to be the doc comment on the fixture:
** This comment is the specification. @Fixture class MyFixture { }
By doing so, every line in the doc comment must start with a double asterisk **
. The specification may exist in its own file, just give a URL to its location in the @Fixture
facet:
** This comment is the specification. @Fixture { specification=`/myproj/specs/Spec1.fandoc` } class MyFixture { }
Specifications, when they exist in their own file, do not start each line with a double asterisk **
.
TIP: Use Fandoc Viewer to edit fandoc files and specifications.
Specifications can be written in any way you wish, but the following structure is very useful. It is written here as a fandoc comment so you may cut and paste it into your specifications.
** Heading ** ####### ** Give some background information and explain the problem at hand. ** ** As a... ** When I... ** I want... ** ** Example ** ------- ** Now describe an example scenario and the expected behaviour. This will be the test: ** ** Given... ** When... ** Then... ** ** Only the example should contain commands. ** ** Further Details ** =============== ** - [link to other fixtures here]`run:OtherTest` ** - [that explain edge cases]`run:MoreTests`
Commands
set
The set
command sets a field of the fixture to the value of the link text. The Str
is coercered to the field's type.
** The meaning of life is [42]`set:number`. @Fixture class ExampleFixture { Int? number }
execute
The execute
command calls a method on the fixture. The cmd is compiled as Fantom code so may be any valid Fantom code.
Any occurrences of the token #TEXT
are replaced with the command / link text.
** [The end has come.]`execute:initiateShutdownSequence(42, #TEXT, "/tmp/end.txt".toUri)` @Fixture class ExampleFixture { Void initiateShutdownSequence(Int num, Str cmdText, Uri url) { ... } }
verify
The verify
command executes a Test verify method against the link text. Available verify methods are:
- eq(...)
- notEq(...)
- type(...)
- true(...)
- false(...)
- null(...)
- notNull(...)
Arguments to the verify methods are run against the fixture and may be any valid Fantom code.
** The meaning of life is [42]`verify:eq(number)`. @Fixture class ExampleFixture { Int? number := 43 }
Arguments for the eq()
and notEq()
methods are type coerced to a Str
. Arguments for the true()
and false()
are type coerced to a Bool
.
fail
This simple command fails the test with the given message.
** The meaning of life is [42]`fail:TODO`. @Fixture class ExampleFixture { }
run
The run
command runs another Fancordion fixture and prints an appropriate success / failure link to it.
The command path must be the name of the Fixture type to run. The fixture type may be qualified.
Use run
commands to create a specification containing a list of all acceptance tests for a feature, in a similar way you would use a test suite.
You could even nest specifications to form a hierarchical index, with results aggregated to display a single green / red / grey result.
** Questions: ** - [Why is the sky blue?]`run:BlueSkyFixture`. @Fixture class ExampleFixture { }
link
The link
command renders a standard HTML <a> tag. It is added with the file
, http
, https
and mailto
schemes.
** Be sure to check out [Fantom-Factory]`http://www.fantomfactory.org/`. @Fixture class ExampleFixture { }
embed
The embed
command executes the given function against the fixture and embeds the results as raw HTML.
Use it to add extra markup to your fixtures.
** Kids, don't play with [FIRE!]`embed:danger(#TEXT)`. @Fixture class ExampleFixture { Str danger(Str text) { """<span class="danger">${text}</span>""" } }
Test BedSheet Apps
Fancordion can be used to test BedSheet applications.
Typically I would start the web application under test (via Bounce) in the runner's suiteSetup()
. Since all web application state is (usually) stored in a database, there is little need to re-start the web app for every test. While this only saves you a couple of seconds, over the course of many tests it can add up to be quite a time saver!
Web application shutdown would then occur in the runner's suiteTearDown()
method.
Below shows a typical FancordionRunner setup together with an abstract WebFixture class.
using afBounce using afFancordion class MyFancordionRunner : FancordionRunner { private BedServer? server new make(|This|? f := null) : super(f) { outputDir = `fancordion-results/`.toFile // other runner configuration... } override Void suiteSetup() { super.suiteSetup server = BedServer(AppModule#.pod).addModule(WebTestModule#).startup } override Void suiteTearDown(Type:FixtureResult resultsCache) { server?.shutdown super.suiteTearDown(resultsCache) } override Void fixtureSetup(Obj fixtureInstance) { webFixture := ((WebFixture) fixtureInstance) super.fixtureSetup(fixtureInstance) webFixture.client = server.makeClient server.injectIntoFields(webFixture) webFixture.fixtureSetup() } override Void fixtureTearDown(Obj fixtureInstance, FixtureResult result) { webFixture := ((WebFixture) fixtureInstance) webFixture.fixtureTearDown super.fixtureTearDown(fixtureInstance, result) } } class WebTestModule { @Contribute { serviceType=ServiceOverrides# } static Void contributeServiceOverride(MappedConfig config) { config["IocEnv"] = IocEnv.fromStr("Testing") } // other test specific services and overrides... } // The super class for all Web Fixtures abstract class WebFixture : FixtureTest { BedClient? client virtual Void fixtureSetup() { } virtual Void fixtureTearDown() { } // The important bit - this creates the FancordionRunner to be used. override FancordionRunner fancordionRunner() { MyFancordionRunner() } // Other common / reusable methods such as : // loginAs(...), logout(), gotoPage(...), etc... }
Release Notes
v0.0.4
- New: Project renamed to
Fancordion
- see Concordion for Fantom. - New: Added
FancordionRunner.current()
that returns the currentFancordionRunner
in use, ornull
if none. - Chg:
FixtureTest
now extendsTest
.
v0.0.2
- New: Preview release.