Yaml Tests is a simple composer plugin tthat make it as simple as possible to define and run a set of tests.
The plugin provides a composer command that simply reads a YML file and runs the lines as a process.
The output is rendered in a way to be easier to read, and proper exit code returns if a single process fails.
It can be installed "locally" (included in your composer.json file) or "globally" (installed into the global "composer" command.
Keeping yaml-tests
in your composer.json
(local install) is the most stable way to operate, since the version is pinned.
cd my-composer-project
composer require provision-ops/yaml-tests
composer global require provision-ops/yaml-tests
To confirm the command is installed, ask for help:
composer yaml-tests --help
If you pass yaml-tests
a GitHub Token, it will send the test results as
"commit status" indicators.
There are 3 ways to pass the GitHub Token to YamlTests:
--github-token
command line option. Don't use this in CI, or you might expose your GitHub token in logs.Recommended: Create a .env
file in your repo, or in your user's home directory:
GITHUB_TOKEN=abcdefg
There is a .env.example
file in this directory you can use as an example.
By default the composer yaml-tests
command looks for a tests.yml file in the project root. You can also pass a path using the --tests-file
option.
The tests.yml
file is read as a simple collection of commands. The key can be any string, as long as it is unique in the test suite.
test/dir: pwd
test/environment: env
You can also include commands in a list:
lint:
- find src -name '*.php' -print0 | xargs -0 -n1 php -l
- find web/modules/custom -name '*.php' -print0 | xargs -0 -n1 php -l
- find tests/src -name '*.php' -print0 | xargs -0 -n1 php -l
You can include a description for each test like:
debug:
command: env
description: Current Environment
Yaml Tests work like Composer Scripts: If your project has the config.bin-dir
set in composer.json
, Composer will automatically add that directory to the PATH when scripts or other commands are run.
For example, you can include PHPUnit and call it without specifying the full path in composer scripts or tests.yml
composer.json
:
{
"config": {
"bin-dir": "bin/"
},
"require": {
"provision-ops/yaml-tests": "^1.1",
"phpunit/phpunit": "^8.1"
},
"scripts": {
"test": [
"which phpunit",
"phpunit --version"
]
}
}
Having the scripts.test
section in composer.json
creates a composer command called composer test
.
tests.yml
:
test/debug:
- which phpunit
- phpunit --version
If you want to only maintain one set of scripts, you can reference composer scripts in tests.yml
:
tests.yml
:
test/debug: composer test
Once the tests.yml
file is in place, and the composer yaml-tests
command is available, you can trigger test runs.
This plugin was also designed to pass these tests as "Commit Statuses" on GitHub. This allows us to tag the results to the specific commit, pass or fail.
If the environment variable GITHUB_TOKEN
or the command line option --github-token
is NOT set, the --dry-run
option will be forced.
Use the --dry-run
option if you have a token set but do not want to post test results to GitHub.
Run composer yaml-tests
or, just like all composer commands, you can use shortcuts like compose y
.
composer yaml-tests
The output will look something like this:
And you will get a nice summary at the end like this:
There is now a "bin" for yaml-tests, allowing the command to be run by itself.
If you require provision-ops/yaml-tests, you will see a link to yaml-tests
in your bin-dir
.