CIVET Extension

The CIVET extension adds the ability for MooseDocs to download results from a CIVET client (e.g., https://civet.inl.gov) and present them as reports, links, badges, and other information in a MooseDocs page. This extension is most-often used with the Software Quality Assurance Extension.

Extension Configuration

Table 1 lists the available configuration settings for the CIVET extension. These configuration items should be included in the MooseDocs configuration file (e.g., config.yml).

Table 1: Configuration options for the CIVET extension.

Key	Default	Description
active	True	Toggle for disabling the extension. This only changes the initial active state, use setActive to control at runtime.
remotes	{}	Remote CIVET repositories to pull result; each item in the dict should have another dict with a 'url', 'repo', and 'repo_url'.
branch	master	The main stable branch for extracting test results.
download_test_results	True	Automatically download and aggregate test results for the current merge commits.
generate_test_reports	True	Generate test report pages, if results exist from download or local file(s).
test_reports_location	civet	The local directory where the generated test reports will be inserted.
test_results_cache	${HOME}/.local/share/civet/jobs	Default location for downloading CIVET results.

Extension Commands

The following sections provide information regarding each of the commands available to the extension.

Results Inline Linking

The results inline command allows for linking to testing results for the version of the code repository used to build the documentation. It generates a single link displaying the git commit SHA which links to the associated CIVET results for that SHA.

Example 1: Example of the CIVET extension results command.

Markdown
HTML

[!civet!results]

e6a7269a5c8e884ea82a7b64ac687043d219022c

Table 2: Options for the CIVET extension results command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	Identifier to link against this object.
remote	None	The category to utilize for remote result lookup, see CivetExtension.
url	None	Override for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repo	None	Override for the repository name provided in the 'category' option, e.g. 'idaholab/moose'.

Merge Results Linking

The civet mergeresults command provides a set of links to CIVET results pages for the version of the code repository used to build the documentation (by default). This is similar to the Results Inline Linking command, except multiple links are provided. Each link is labeled using the git SHA associated with the merge event that prompted testing. This means that MOOSE, for example, might have multiple links associated with next, devel, and master testing events associated with a single master branch merge constituting the current version of the code and documentation. If the use_current_hash settings option is set to False, then the most up-to-date version of the these links is retrieved from the online remote repository.

Example 2: Example of the CIVET extension mergeresults command.

Markdown
HTML

!civet mergeresults

e6a7269a5c8e884ea82a7b64ac687043d219022c
8095e1122397df3f4e736969849f9139204f031f

tip:Inline usage

Note that this command can also be used inline, using the [!civet!mergeresults] syntax.

Table 3: Options for the CIVET extension mergeresults command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	Identifier to link against this object.
remote	None	The category to utilize for remote result lookup, see CivetExtension.
url	None	Override for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repo	None	Override for the repository name provided in the 'category' option, e.g. 'idaholab/moose'.
use_current_hash	True	Use the hash for the current version of the documentation build, otherwise use the most up-to-date hash from the git remote.

Test Results Badges

The badges command allows the display of a badge (or badges) containing the aggregate status of all tests that were completed corresponding to one or more test specifications for the results associated with the version of the code repository used to build the documentation. Clicking on the badge directs the browser to a report page where individual results can be inspected.

Example 3: Examples of the CIVET extension badges command.

Markdown
HTML

With one test specification:

!civet badges tests=kernels/simple_diffusion.test

With two test specifications:

!civet badges tests=kernels/simple_diffusion.test outputs/common.exodus

With one test specification:

With two test specifications:

tip:Inline usage

Note that this command can also be used inline, using the [!civet!badges tests=...] syntax.

Table 4: Options for the CIVET extension badges command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	Identifier to link against this object.
remote	None	The category to utilize for remote result lookup, see CivetExtension.
url	None	Override for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repo	None	Override for the repository name provided in the 'category' option, e.g. 'idaholab/moose'.
tests	None	The name of the test(s) to report.

Test Results Report

The report command generates a table of jobs, associated CIVET recipes, and test statuses for a given test specification. While this command is available for general use within any markdown page, the table generation activity called by this command is generally used within the Test Results Badges command, where a results page is generated for linking to the rendered badge.

Example 4: Example of the CIVET extension report command.

Markdown
HTML

!civet report tests=kernels/simple_diffusion.test

Status	Job	Recipe

Table 5: Options for the CIVET extension report command.

Key	Default	Description
style	None	The style settings that are passed to rendered HTML tag.
class	None	The class settings to be passed to rendered HTML tag.
id	None	Identifier to link against this object.
remote	None	The category to utilize for remote result lookup, see CivetExtension.
url	None	Override for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repo	None	Override for the repository name provided in the 'category' option, e.g. 'idaholab/moose'.
tests	None	The name of the test(s) to report.

Extension Configuration
Extension Commands