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.

KeyDefaultDescription
activeTrueToggle 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'.
branchmasterThe main stable branch for extracting test results.
download_test_resultsTrueAutomatically download and aggregate test results for the current merge commits.
generate_test_reportsTrueGenerate test report pages, if results exist from download or local file(s).
test_reports_locationcivetThe local directory where the generated test reports will be inserted.
test_results_cache${HOME}/.local/share/civet/jobsDefault 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.

Table 2: Options for the CIVET extension results command.

KeyDefaultDescription
styleNoneThe style settings that are passed to rendered HTML tag.
classNoneThe class settings to be passed to rendered HTML tag.
idNoneIdentifier to link against this object.
remoteNoneThe category to utilize for remote result lookup, see CivetExtension.
urlNoneOverride for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repoNoneOverride 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.

schooltip: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.

KeyDefaultDescription
styleNoneThe style settings that are passed to rendered HTML tag.
classNoneThe class settings to be passed to rendered HTML tag.
idNoneIdentifier to link against this object.
remoteNoneThe category to utilize for remote result lookup, see CivetExtension.
urlNoneOverride for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repoNoneOverride for the repository name provided in the 'category' option, e.g. 'idaholab/moose'.
use_current_hashTrueUse 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.

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:

schooltip: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.

KeyDefaultDescription
styleNoneThe style settings that are passed to rendered HTML tag.
classNoneThe class settings to be passed to rendered HTML tag.
idNoneIdentifier to link against this object.
remoteNoneThe category to utilize for remote result lookup, see CivetExtension.
urlNoneOverride for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repoNoneOverride for the repository name provided in the 'category' option, e.g. 'idaholab/moose'.
testsNoneThe 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.

!civet report tests=kernels/simple_diffusion.test

StatusJobRecipe
OK437183904_Test_moose_test
OK437184004_Test_moose_test
OK437184104_Test_moose_test
OK437184204_Test_moose_test
OK437184604_Test_moose_test
OK437185204_Test_moose_test
OK437185306_Test_moose_test
OK437185404_Test_-p_4
OK437185405_Test_-p_6
OK437185406_Test_-p_8
OK437185407_Test_-p_16
OK437185504_Test_distributed_mesh_with_recover
OK437185505_Test_-p_3
OK437185506_Test_-p_5
OK437185507_Test_-p_7
OK437185508_Test_-p_15
OK437185604_Test_-p_4
OK437185605_Test_-p_6
OK437185606_Test_-p_8
OK437185607_Test_-p_16
OK437185704_Test_-p_3
OK437185705_Test_-p_5
OK437185706_Test_-p_7
OK437185707_Test_-p_15
OK437186413_Test_tutorialstutorial02
OK437186612_Test_moose_test
OK437186613_Test_moose_test_-p_2
OK437186614_Test_moose_test_--recover
OK437186707_Test_moose_test_--n-threads_2
OK437186708_Test_moose_test_--distributed-mesh_-p_2
OK437186710_Test_moose_test_--restep
OK437186807_Test_moose_test
OK437186808_Test_moose_test_-p_2
OK437186904_Test_moose_test
OK437187004_Test_moose_test
OK437187506_Test_moose_test
OK437188403_Test_moose_test
OK437188504_Test_-p_2
OK437188604_Test_-p_4
OK437188605_Test_-p_6
OK437188606_Test_-p_8
OK437188607_Test_-p_16
OK437188704_Test_-p_3
OK437188705_Test_-p_5
OK437188706_Test_-p_7
OK437188707_Test_-p_15
OK437188830_Test_mastodon
OK437188839_Test_open_pronghorn
OK437188845_Test_salamander
OK437188854_Test_Stork
OK437189604_Test_-p_4
OK437189605_Test_-p_6
OK437189606_Test_-p_8
OK437189607_Test_-p_16
OK437189704_Test_-p_3
OK437189705_Test_-p_5
OK437189706_Test_-p_7
OK437189707_Test_-p_15
OK437189803_Test_moose_test_and_store
OK437481507_Test_moose_test
OK437481508_Test_moose_test_-p_2
OK437481509_Test_moose_test_--recover
OK437481510_Test_moose_test_--n-threads2
OK437481511_Test_moose_test_--distributed-mesh_-p_2
OK437481907_Test_moose_test
OK437482007_Test_moose_test
OK437482105_Test_moose_test
OK437482106_Test_moose_test_-p_2
OK437482107_Test_moose_test_--recover
OK437482108_Test_moose_test_--n-threads2
OK437482109_Test_moose_test_--distributed-mesh_-p_2
OK437482804_Test_moose_test_--valgrind

Table 5: Options for the CIVET extension report command.

KeyDefaultDescription
styleNoneThe style settings that are passed to rendered HTML tag.
classNoneThe class settings to be passed to rendered HTML tag.
idNoneIdentifier to link against this object.
remoteNoneThe category to utilize for remote result lookup, see CivetExtension.
urlNoneOverride for the repository url provided in the 'category' option, e.g. 'https://civet.inl.gov'.
repoNoneOverride for the repository name provided in the 'category' option, e.g. 'idaholab/moose'.
testsNoneThe name of the test(s) to report.