Extension:MWUnit/Annotations

An annotation is a special form of metadata that can be added to the source code of some programming languages. In the case of MWUnit, annotations are added through tag attributes. This appendix shows all the annotations supported by MWUnit.

Annotations

@name

The name annotation is a required annotation. It is used to give an identifying name to a test case. The name for each test case on a page should be unique.

...
<testcase name="testFoobar" group="foobar test"> <!-- We will talk more about the "group" annotation later -->
...

@group

A test must be tagged as belonging to one, and only one, group. This is done through the group annotation.

...
<testcase name="testFoobar" group="foobar test">
...

@context

Further information: Extension:MWUnit/Contexts

The context annotation can be used to run the test in a specific context. By default, tests are run in a canonical context. This means the parser is initialized with an anonymous user and the content language. This is done to make the output of the test consistent across users and languages.

You can choose to run a specific test in user context using the context annotation. A test run in user context will initialize the parser with the current logged in user or the user specified by the "@user" annotation and the language that the user has set. This can be useful for testing templates that depend on if the user is logged in or who is logged in or which language is selected.

The context annotation can either be left empty, have the value canonical or have the value user.

...
<testcase name="testFoobar" group="foobar test" context="user">
...
</testcase>

<testcase name="testFoobar" group="foobar test" context="canonical">
...
</testcase>
...

@user

When a test is run in a "user" context, it is sometimes useful to be able to control as which user the test should be run. When no "@user" annotation is supplied, the test will be run in the context of the currently logged in user. If a user is supplied in the "@user" annotation, and running tests as another user is not disabled, the test will be run as if it were run by the specified user.

@covers

The @covers annotation can be used to specify which template the test is supposed to test.

<testcase name="testFoobar" group="foobar test" covers="Foobar">
...
</testcase>

If provided, it will add a button to run the associated test(s) on the template page in the sidebar. When $wgMWUnitStrictCoverage is set to true, MWUnit will perform additional checks to make sure the template covered in a test is actually used in that test.

These checks are performed by hooking into the ParserFetchTemplate hook and checking if that hook is ever fired during the test case with the template specified in the annotation. Since the MediaWiki parser caches template fetches, this hook is only ever called once per template. This would mean if we created a variable (through the Variables extension)in the fixture with that template, the hook would not get called in the test case. To remedy this, the initial parser before the first test case is cloned and stored. Before the test is run, we check if the template specified in the @covers annotation is in the initial parser's cache and presume it is used if it is. This may rarely lead to false negatives, unfortunately.

When the $wgMWUnitForceCoversAnnotation configuration option is set to true, every test must have an associated @covers annotation.

@ignoreStrictCoverage

The @ignoreStrictCoverage annotation can be used to skip coverage check for any particular test case. When given, MWUnit will not perform any additional checks to make sure the template is covered, regardless of the value of $wgMWUnitStrictCoverage.

@doesNotPerformAssertions

The @doesNotPerformAssertions annotation can be used to tell MWUnit to not execute any assertion checks on the test case. This means that MWUnit will not mark the test as risky because it does not perform any assertions.

@skip

The @skip annotation can be used to skip the test case.

@requires

The @requires annotation can be used to express preconditions for a test case. This annotation takes a comma-separated list of extension names and will only perform the test case if all specified extensions are loaded.