civicarrot.json syntax

By DaveD, 29 January, 2024

The file civicarrot.json is expected to be in the "tests" folder, i.e. <extension_root>/tests/civicarrot.json. It contains two main keys, both optional: singlePR and periodic.

For singlePR, it expects an "include" array where the object elements have three keys: "php-versions", "drupal", and "civicrm". Each object in the array will generate a parallel test run with its own parameters. For example this configuration will have two test runs:

{
  "singlePR": {
    "include": [
      {
        "php-versions": "8.1",
        "drupal": "10.0.*",
        "civicrm": "dev-master"
      },
      {
        "php-versions": "7.4",
        "drupal": "~9.5.1",
        "civicrm": "^5.63.0"
      }
    ]
  }
}

php-versions can be either a specific major.minor version, or the placeholder string CIVICARROT_PHP_SENSIBLE, which means the lowest "green" version listed at https://www.php.net/supported-versions.php
drupal and civicrm values are either any string understood by composer, or placeholder strings as below:

CIVICARROT_CIVI_LATEST: Whatever the latest released version is, e.g. 5.12.3
CIVICARROT_CIVI_RELEASECANDIDATE: One higher minor version than the latest released version, e.g. 5.13.x-dev
CIVICARROT_CIVI_DEV: Just an alias for 'dev-master'
CIVICARROT_DRUPAL_LATEST: Due to historical accident¹, this is the "next" version, e.g. if 10.1.1 is the released version, this is 10.2.x-dev.
CIVICARROT_DRUPAL_PRIOR: Again due to historical accident, this is the current released version.

For "periodic", you can set up multiple schedules that run at different times. The top-level key is an arbitrary name you can give the schedule. Then below it you can have the following keys:

cronSpec: This is the same as a standard crontab, e.g. "30 3 * * *" means 03:30 every day. Times are UTC.
testType: Either "all", "mink", or "plain". This depends on what type of tests you have. CiviCRM core-like tests are "plain".
matrix: This just has a subkey "include" which is the same as for "singlePR" above.

Example:

{
  "singlePR": {
    "include": [
      {
        "php-versions": "8.2",
        "drupal": "CIVICARROT_DRUPAL_PRIOR",
        "civicrm": "dev-master"
      },
      {
        "php-versions": "7.4",
        "drupal": "9.5.*",
        "civicrm": "5.63.*"
      }
    ]
  },
  "periodic": {
    "MyDaily": {
      "cronSpec": "30 3 * * *",
      "testType": "all",
      "matrix": {
        "include": [
          {
            "php-versions": "CIVICARROT_PHP_SENSIBLE",
            "drupal": "CIVICARROT_DRUPAL_PRIOR",
            "civicrm": "dev-master"
          },
          {
            "php-versions": "8.1",
            "drupal": "CIVICARROT_DRUPAL_PRIOR",
            "civicrm": "CIVICARROT_CIVI_RELEASECANDIDATE"
          },
          {
            "php-versions": "8.1",
            "drupal": "CIVICARROT_DRUPAL_PRIOR",
            "civicrm": "CIVICARROT_CIVI_LATEST"
          },
          {
            "php-versions": "7.4",
            "drupal": "~9.5.11",
            "civicrm": "~5.63.0"
          }
        ]
      }
    }
  }
}

Note that changes to the "periodic" section might not get picked up right away. It's cached so may take a cycle to refresh.

Footnotes

1. At the time this was being developed, there was no drupal beta version being returned from packagist queries, so it appeared as though it worked the same way as packagist queries for civicrm. Hence the mismatch in the placeholder terms.