Concordion > Commands >

Example

Since Concordion 2.0.0

Concordion has support for specifications containing examples. These are run as seperate jUnit tests.

The example command also supports the example listener.

Before

To specify that a piece of HTML should be run before each example, annotate the enclosing HTML tag with the concordion:example tag, putting the keyword "before" in the expression

<div concordion:example="before">
        ...Example goes here
</div>
In this case, we simply reset a counter.
<span c:execute="setCounter('10')"/>

And set a variable for use in an example

<span c:set="#are = 'are'"/>

Of course, you can have tables in a before example - this can be useful for populating a database with data

Table RowDescription
1A database row
2Another database row

Example 1

To specify that a piece of HTML is an example, annotate the enclosing HTML tag with the concordion:example tag, putting your example name in the expression. Do not use "before" as your example name as Concordion will intrepret your example as a piece of your spec that must be executed before each example.

<div concordion:example="example1">
        Example goes here
</div>

Note that the class of "example" is optional - the default concordion stylesheet will make the example look pretty

In this case, we can assert that our counter is 10 and then increment the counter so that other examples will fail if the before part of the specification is not run. The counter is now 11

Namespaces in examples are separate. So if you set a variable in your spec to a value, then other examples will not have access to that value. To prove this, in both examples we assert that #notshared variable is null and then set it to "a value". We do this in both examples to counter running order effects.

Of course, variables set in the before example are accessible (but changes to them in one example are not visible in the other examples)

Note that methods in the fixture class annotated with @BeforeSpecification are executed exactly once before any examples are run. Methods annotated with @AfterSpecification are executed after the specification has executed.

Finally, we assert that 2 table rows were added to our database.

Another Example

This is a separate example in the specification. Note that concordion automatically adds an id attribute anchor into the output HTML so you can link to particular examples. The value of the concordion:example attribute is used for the id. For example, you can link to this example by adding #example2 to the URL.

<div concordion:example="example2">
        Example goes here
</div>

In this case, we also assert that our counter is 10 and then increment the counter so that other examples will fail if the before part of the specification is not run. The counter is now 11

Namespaces in examples are separate. So if you set a variable in one example to a value using something like

<span c:set="#notshared"/>

Then other examples will not have access to that value. To prove this, in both examples we assert that #notshared variable is null and then set it to "a value". We do this in both examples to counter running order effects.

Of course, variables set in the before example are accessible.

Note that methods in the fixture class annotated with @BeforeSpecification are executed exactly once before any examples are run. Methods annotated with @AfterSpecification are executed after the specification has executed.

Finally, we assert that 2 table rows were added to our database.

Tables

Concordion can execute each row in a table as an example. To do this, use the c:example tag in one of the table header columns and specify the example name in the corresponding column of each row.

For example:

    <table c:execute="#counter = incrementCounter()">
        <tr>
            <th c:example="">Example Name</th>
            <th c:assertEquals="#counter">Counter value</th>
        </tr>
        <tr c:status="ExpectedToFail">
            <td>1st Table Example</td>
            <td>12</td>
        </tr>
        <tr>
            <td>2nd Table Example</td>
            <td>11</td>
        </tr>
        <tr>
            <td>3rd Table Example</td>
            <td>11</td>
        </tr>
    </table>
Example Name Counter value

1st Table Example
11

2nd Table Example
11

3rd Table Example
11
Example Name Counter value

4th Table Example
11

5th Table Example
11

6th Table Example
11

Run Results

When reporting run results for the specification as a whole, Concordion sums the success, failure, ignored, or exception counts from each example in the specification.

For example, a spec (LotsOfExamples.html) with two successful examples, a failed example, an an exception example with a total of 10 successes, 2 failures and 2 exceptions returns 10 successes, 2 failure, 2 exceptions, and 0 ignores

Tests outside any example

Tests outside of any example block (the tests in this block are outside an example block) are still executed and the results of these tests are reported back in the same way as if the test had no examples:

A spec (AssertsOutsideExamples.html) with a successful example containing 2 successful assertions and two assertions outside the example, one of which fails, returns 3 successes, 1 failure, 0 exceptions, and 0 ignores

Finally, we assert that 2 table rows were added to our database.

Fixture Instances

A new fixture instance is created for each example, in keeping with the way that JUnit creates a new instance per test.

Field reuse

Fixture fields can be scoped for reuse across a specification, in addition to the default example scope.

Method hooks

@BeforeExample and @AfterExample methods are called for each example, including the "outer" example.

In addition, you can use example listeners.

Expected to Fail

Concordion examples can be marked as expected to fail:

<div concordion:example="example3" concordion:status="ExpectedToFail">
        Example goes here
</div>

A spec (ExamplesMarkedExpectedToFail.html) with an unimplemented example, a successful example and a failing example all marked as ExpectedToFail, returns 0 successes, 2 failures, 0 exceptions, and 1 ignores.

Expected to Fail with Fail-Fast

When calling another specification that fails fast on an example that is expected to fail, the result is "ignored".

Ignored

Concordion examples can also be marked as ignored:

<div concordion:example="example3" concordion:status="Ignored">
        Example goes here
</div>

A spec (ExamplesMarkedIgnored.html) with an ignored example, returns 0 successes, 0 failures, 0 exceptions, and 1 ignores.

Unimplemented

Concordion examples can be marked as unimplemented.

<div concordion:example="unimplemented" concordion:status="Unimplemented">
        Example goes here
</div>

Any asserts done in the example will cause the example to fail the spec.

A spec (ExamplesMarkedUnimplemented.html) with an unimplemented example, a successful example and a failing example all marked as Unimplemented, returns 0 successes, 2 failure, 0 exceptions, and 1 ignores.