Global tests

Global tests are run whenever a Swarm review is started or updated. This ensures that the global tests are enforced for all changes even if they are not part of a project.

To add a global test, edit the SWARM_ROOT/data/config.php file and add the global test details to the global_tests section of the configuration block. For example:

<?php
    // this block should be a peer of 'p4'
    'global_tests' => array(
        array( 
            'name' => 'myglobaltest01',
            'title' => 'Title for this test',
            'url' => 'http://my-test-server/build?change={change}&testname={test}&status={status}',
            'body' => 'foo=bar&review={review}&reviewversion={version}&testrun={testRunId}&project={projectNames}', // optional		
            'encoding' => 'url', // 'url|json', optional, defaults to 'url'
            'headers' => array(
                'BasicAuth' => 'user:password',
                'OtherHeader' => 'OtherValue', // optional
            ),
            'timeout' => 30,  // HTTP timeout in Seconds, optional.  
                              // If timeout is not set here, Swarm uses the timeout set in 'http_client_options'
        ),
        array(
            'name' => 'myglobaltest02',
            'title' => 'Title for my second test',
            'url' => 'http://my-other-test-server/build?change={change}&testname={test}&reviewstate={reviewStatus}',
            'body' => 'foo=bar&baz=buzz&review={review}&reviewversion={version}&branches={branches}&changedescription={description}', // optional		
            'encoding' => 'url', // 'url|json', optional, defaults to 'url'
            'headers' => array(
                'BasicAuth' => 'user:password',
                'OtherHeader' => 'OtherValue', // optional
            ),
            'timeout' => 30,  // HTTP timeout in Seconds, optional.
                              // If timeout is not set here, Swarm uses the timeout set in 'http_client_options' 
        ),
    ),	

• name: specify a unique name for the test. 1 to 32 characters, valid characters are -_A-Za-z0-9.
Important
• It is important that each global test has a unique name. If you have two global tests with the same name, neither of them will run.
• If you change the name of a global test, you must also change it in any Test Integration APIs you have that call that test.
• title: specify a friendly name for the test, 1 to 64 characters
• url: specify the URL that triggers your test suite execution. Special arguments are also available to pass details from Swarm to your test suite, see Pass special arguments to your test suite.
• body optional: specify parameters that your test suite requires. Special arguments are also available to pass details from Swarm to your test suite, see Pass special arguments to your test suite.
• encoding optional: select the format to POST parameters, either URL encoded or JSON encoded:
  • url: POST parameters are parsed into name=value pairs. url is the default.
  • json: parameters are passed raw in the POST body.
• headers optional: specify any name=value pairs you want to pass to the test suite.
• timeout optional: set a timeout in seconds (integer), used when Swarm connects to your test suite.
Tip

If timeout is not set for a global test, Swarm uses the timeout set in http_client_options, see HTTP client options.

Pass special arguments to your test suite

You can include special arguments in the url and body to pass Swarm information about the change that triggered the test run to your test suite. Swarm automatically replaces the arguments with the relevant Swarm information when it calls the test:

• {change} the change number
• {status} the status of the shelved change, shelved or committed
• {review} the review identifier
• {version} the version of the review
• {reviewStatus} the Swarm status of the review: needsReview, needsRevision, archived, rejected, approved, approved:commit
• {description} the change description of the change used to generate this update. {description} cannot be used in the url, it can only be used in the body.
• {test} the name of the test
• {testRunId} the test run id
• {projects} the project identifiers of projects that are part of the review, null if the review is not part of a project. Comma separated if more than one project is involved in the review.
• {projectNames} the project names of projects that are part of the review, null if the review is not part of a project. Comma separated if more than one project is involved in the review.
• {branches} the branch identifiers of branches that are part of the review. Branch identifiers are prefixed by a project identifier (with a colon : separator) if the branch is part of a project, null if the branch is not part of a project. Comma separated if more than one branch is involved in the review.
• {update} the update callback URL. You can include any or all of the following when calling the update url to update the test run: test status, messages, and a url in the body that links to the CI system for that run. They should be formatted in JSON in the body of the POST request. Test status: valid test status values are running, pass, and fail. Messages: you can pass a maximum 10 messages, if you provide more than 10 messages only the first 10 are saved. Each message can contain a maximum of 80 characters, any messages with more than 80 characters will be automatically truncated. {update} is the preferred option for Swarm 2019.3. For more details, see the note below.
• {pass} the tests pass callback URL. From Swarm 2019.3, {update} is preferred. For more details, see the note below.
• {fail} the tests fail callback URL. From Swarm 2019.3, {update} is preferred. For more details, see the note below.
Note
• Swarm 2019.3 and later still supports {pass} and {fail}, however {update} is preferred because you can also include a message with the test status.
• {update}, {pass}, and {fail} are composed automatically by Swarm, they include Swarm's own per-review authentication tokens.