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.

@name
The  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, but this is not enforced. MWUnit does throw an exception when a name is reused, but it will still run the test without any issue.

...  ...

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

...  ...

Tests can be selected for executed based on group via the special page.

@context
The  annotation can be used to run the test in a specific context. By default, tests are ran 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  annotation. A test run in user context will initialise the parser with the current logged in user or the user specified by the "@user" annotation and the language that 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  annotation can either be left empty, have the value   or have the value.

...  ...

 ... ...

@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 ran. When no "@user" annotation is supplied, the test will be run in the context of the current logged us.

If a valid 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  annotation can be used to specify which template the test is supposed to test.

 ...

If provided, it will add a button to run the associated test(s) on the template page in the sidebar. When  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  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  configuration option is set to , every test must have an associated   annotation.

@ignoreStrictCoverage
The  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.