A guide for drupal.org project maintainers.
Note: Put this in a handbook page when it's been RTBCd.
DrupalCI is a system that checks out the quality of projects hosted on drupal.org. We sometimes call it the 'testbot.'
The DrupalCI testbot uses a YAML-formatted file to specify a 'build.' The build is all the things that happen when the testbot evaluates your patch.
The build definition file tells the testbot how to retrieve the codebase it's supposed to test, how to apply patches, how to run Composer, and so forth.
If you look at the default definition file, you'll see that it has a top-level key of build
.
Under the build
level we have what are called stages. These include codebase
, environment
, and assessment
.
Within these stages are 'phases,' such as validate_codebase
and testing
. The generic term for any item in the build definition is a 'task.'
If you want your testbot builds to do something other than the default build, you should put it into a drupalci.yml
file in the root of your project.
It should look like this:
build:
assessment:
# Your assessment stage stuff here.
Remember we said there are 'stages?' Well, your drupalci.yml
file will replace the assessment
stage. If you have a codebase
or environment
stage in your file, they will be ignored. That's so the testbot doesn't lose its mind.
You can use the tasks you see in the default file. They are not as greatly documented as they should be, but that will change.
You can also issue commands to the host environment and the containerized environment, like this:
host_command:
- test -f vendor/composer/installed.json
- another command/here
container_command:
- composer update phpunit/phpunit --with-dependencies
You can also specify whether these tasks will halt the build or not. die-on-nonzero
refers to the result code of the command you executed:
container_command:
die-on-nonzero: TRUE
- composer update phpunit/phpunit --with-dependencies
And, finally, you can have more than one of these, if you give it a name by adding .name
to the end of the task:
container_command.setup:
die-on-nonzero: FALSE
- setup your/thing
- setup other/thing
container_command.showstopper:
die-on-nonzero: TRUE
- showstopper -v
Currently, the testbot uses Docker to provide the PHP environment. If you want to run a PHP command in the PHP version you specified on D.O, you should run it under container_command
.
Otherwise, host_command
has a PHP version of 7.2, and might not in the future.
In addition to host_command
and container_command
, we have these ones, which you have to put inside their validate_codebase
and testing
keys:
validate_codebase:
phplint:
container_composer:
csslint:
eslint:
phpcs:
testing:
simpletest.standard:
types: 'Simpletest,PHPUnit-Unit,PHPUnit-Kernel,PHPUnit-Functional'
simpletest.js:
concurrency: 1
types: 'PHPUnit-FunctionalJavascript'
nightwatchjs:
They all have configurations which you can learn about by examining the result builds of previous testbot runs, or by looking at them in code.
MORE DOCS PLEEZE.