Fragments API

In specs2 a specification can simply be viewed as a sequence of “Fragments”. A Fragment is something which has:

All the elements encountered in this User Guide fall under this representation:

The role of the various DSLs in acceptance and unit specifications is to create those fragments and assemble them into a bigger Fragments object. They do this using:

The FragmentFactory API

The org.specs2.specification.create.FragmentFactory trait possesses different methods to create:

Please have a look at the ScalaDoc to see the exact API for the factory and look at the source code for the default implementation in org.specs2.specification.create.DefaultFragmentFactory.

The Fragments API

If you know how to create examples, texts and steps you will need to append them together as Fragments. You can create a Fragments object by using Fragments.apply:

val ff = fragmentFactory

Fragments(ff.text("introduction"), ff.example("first example", success), ff.break)

Then you can use the methods of the org.specs2.specification.core.Fragments class to add more fragments or to modify existing ones:

Method Description
append(f: Fragment) to append a single fragment
append(fs: Fragments) to append another Fragments object
prepend(...) to do the same as above but prepending instead of appending
append(fs: Seq[Fragment]) to append a sequence
filter(f: Fragment => Boolean) to filter out some fragments
map(f: Fragment => Fragment) to modify each fragment
mapDescription(f: Description => Description) to just modify the descriptions

The Fragments DSL

The org.specs2.specification.dsl.FragmentsDsl trait provides a very versatile ^ operator to append fragments together, so you can write:

val ff = fragmentFactory

val fs = Fragments(ff.text("introduction"), ff.example("first example", success), ff.break)
val f1 = ff.text("f1")

// all those combinations are possible and return a `Fragment` object
fs ^ f1
f1 ^ fs
fs ^ fs
f1 ^ f1