auto testing a template

The $test{} directive specifies test data
within the template itself, that will be used to evaluate
the template when template.test() is called.
test directives have no effect on output generated
when a template is evoque’d.

Parameters

May specify sample data, as keyword parameters that the template
may need.
Positional arguments are not supported — only keyword args.

$test{ **kw }

From an application, any tests are executed with:

template.test() -> [qsclass]

Example

$if{ is_good }
    <p class="yes">Good for you, ${first}!</p>
$elif{ is_adult }
    <p class="adult">Think again, ${last}.</p> 
$else
    <p class="minor">
        That is not quite right ${first}. Try again!
    </p> 
$fi
$test{is_good=True, is_adult=True, first="Jo", last="Dough"}
$test{is_good=False}
$test{is_adult=False}

Executing template.test() for the above template will thus
evaluate it 3 times, one for each test directive specified. Any parameter
not specified in a test directive will inherit its value from
the previous test directive.
In this case the test data provides for coverage of all the possible
logical paths, so every piece of the template is exercised.

Combined with template’s default data

Templates may be set-up to define and remember own default data.
This may be done either at initialization (data init parameter)
or via a $prefer{data=dict(**kw)} directive.
If a template’s data attribute is set, the test()
method will use that value as the starting point for the test data cascade.
To illustrate this relation, here’s the example above, adjusted with a
$prefer{} directive and still giving identical
test() results:

$prefer{ data=dict(first="Jo", last="Dough") }
$if{ is_good }
    <p class="yes">Good for you, ${first}!</p>
$elif{ is_adult }
    <p class="adult">Think again, ${last}.</p> 
$else
    <p class="minor">
        That is not quite right ${first}. Try again!
    </p> 
$fi
$test{is_good=True, is_adult=True }
$test{is_good=False}
$test{is_adult=False}

Test directive principles

  • Specify sample test data for the template, nested or not.
  • May specify as many as desired, execution will cascade through them in
    the specified order, i.e. if a kw arg is not specified in current test,
    then its last defined value will be used for this test.
  • If template defines any default data, then that data is
    used as initial data for the tests
    (see Combined with template’s default data, below).
  • Executed simply with template.test(), and if any
    evaluation errors occur they are always raised irrespective
    of the setting for domain.errors.
  • template.test() returns a list of responses,
    one for each test directive. If no test
    directive is specified, a test will always be attempted with either
    the template’s default data or with no data.
  • template.test() on a raw template
    returns None.
  • A test directive must occur at the template’s top level.
  • May also be used to prime the template.evaluator.codes cache.