Template

This page covers maintaining the Vortex template: authoring scripts and testing the template functionality.

Authoring scripts

These requirements apply to all shell scripts in the template: the shipped tooling scripts (see Tooling) and the scripts/ provision subscripts.

Requirements

note

Please refer to RFC2119 for meaning of words MUST, SHOULD and MAY.

MUST adhere to POSIX standard.
MUST pass Shellcheck code analysis scan

MUST start with:

#!/usr/bin/env bash
##
# Action description that the script performs.
#
# More description and usage information with a last empty
# comment line.
#

set -eu
[ "${VORTEX_DEBUG-}" = "1" ] && set -x

MUST list all variables with their default values and descriptions. i.e.:

# Deployment reference, such as a git SHA.
VORTEX_NOTIFY_REF="${VORTEX_NOTIFY_REF:-}"

MUST include a delimiter between variables and the script body preceded and followed by an empty line (3 lines in total):
```
# ------------------------------------------------------------------------------
```

SHOULD include formatting helper functions. info opens and closes an operation, task announces work that is starting, note is a standalone remark that starts no task, and fail prints the message and terminates the script with status 1, or with the status passed as its second argument - it is always the last statement of a failure branch, and anything that explains the failure runs before it:

# @formatter:off
info() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[36m[INFO] %s\033[0m\n" "${1}" || printf "[INFO] %s\n" "${1}"; }
note() { printf "       %s\n" "${1}"; }
task() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[34m[TASK] %s\033[0m\n" "${1}" || printf "[TASK] %s\n" "${1}"; }
pass() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[32m[ OK ] %s\033[0m\n" "${1}" || printf "[ OK ] %s\n" "${1}"; }
fail() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[31m[FAIL] %s\033[0m\n" "${1}" || printf "[FAIL] %s\n" "${1}"; exit "${2:-1}"; }
# @formatter:on

Every task MUST be closed by a pass or a fail - a task announces work that is starting, so it always reports its outcome, even when the work itself cannot fail.

SHOULD include variable values checks with errors and early exit, i.e.:

[ -z "${VORTEX_NOTIFY_REF}" ] && fail "Missing required value for VORTEX_NOTIFY_REF."

SHOULD include binaries checks if the script relies on them, i.e.:

command -v curl > /dev/null || fail "curl command is not available."

MUST contain an info message about the start of the script body, e.g.:

info "Started GitHub notification for operation ${VORTEX_NOTIFY_EVENT}."

MUST contain a pass message about the finish of the script body, e.g.:

pass "Finished GitHub notification for operation ${VORTEX_NOTIFY_EVENT}."

MUST use uppercase global variables.
MUST use lowercase local variables.
MUST use long options instead of short options for readability. I.e., drush cache:rebuild instead of drush cr.
MUST use VORTEX_ prefix for variables, unless it is a known 3-rd party variable like PACKAGE_TOKEN or COMPOSER.
MUST use a script-specific prefix. I.e., for vortex-notify, the variable to skip notifications should start with VORTEX_NOTIFY_.
MAY rely on variables from the external scripts (not prefixed with a script-specific prefix), but MUST declare such variables in the header of the file.
MAY call other Vortex scripts (discouraged), but MUST source them rather than creating a sub-process. This is to allow passing environment variables down the call stack.
SHOULD use note messages for informing about the script progress.
MUST use variables in the form of ${VAR}.

Variables

Follow these guidelines when creating or updating Vortex variables.

Local variables MUST be in lowercase, and global variables MUST be in uppercase.
All Vortex variables MUST start with VORTEX_ to separate Vortex from third-party variables.
Global variables MAY be re-used as-is across scripts. For instance, the WEBROOT variable is used in several scripts.
Vortex action-specific script variables MUST be scoped within their own script. For instance, the VORTEX_PROVISION_OVERRIDE_DB variable in the vortex-provision script.
Drupal-related variables SHOULD start with DRUPAL_ and SHOULD have a module name added as a second prefix. This is to separate Vortex, third-party services variables, and Drupal variables. For instance, to set a user for Drupal's Shield module configuration, use DRUPAL_SHIELD_USER.
Variables SHOULD NOT be exported into the global scope unless absolutely necessary. Thus, values in .env SHOULD have default values set, but SHOULD be commented out to provide visibility and avoid exposure to the global scope.

Boilerplate script

Expand to see the boilerplate script

#!/usr/bin/env bash
##
# Action description that the script performs.
#
# More description and usage information with a last empty
# comment line.
#

set -eu
[ "${VORTEX_DEBUG-}" = "1" ] && set -x

# Example Vortex variable with a default value.
VORTEX_EXAMPLE_URL="${VORTEX_EXAMPLE_URL:-http://example.com}"

# ------------------------------------------------------------------------------

# @formatter:off
info() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[36m[INFO] %s\033[0m\n" "${1}" || printf "[INFO] %s\n" "${1}"; }
note() { printf "       %s\n" "${1}"; }
task() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[34m[TASK] %s\033[0m\n" "${1}" || printf "[TASK] %s\n" "${1}"; }
pass() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[32m[ OK ] %s\033[0m\n" "${1}" || printf "[ OK ] %s\n" "${1}"; }
fail() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[31m[FAIL] %s\033[0m\n" "${1}" || printf "[FAIL] %s\n" "${1}"; exit "${2:-1}"; }
# @formatter:on

info "Started Vortex operations."

[ -z "${VORTEX_EXAMPLE_URL}" ] && fail "Missing required value for VORTEX_EXAMPLE_URL."
command -v curl >/dev/null || fail "curl command is not available."

# Example of the script body. Every task is closed by a pass or a fail. The
# assignment is guarded so a curl transport error reports through fail instead
# of aborting the script via 'set -e' before fail can run.
task "Requesting example page."
if ! status="$(curl -L -s -o /dev/null -w "%{http_code}" "${VORTEX_EXAMPLE_URL}")"; then
  fail "Unable to reach ${VORTEX_EXAMPLE_URL}."
fi
echo "${status}" | grep -q '200\|403' || fail "Example page returned status ${status}."
pass "Requested example page."

pass "Finished Vortex operations."

Testing

Vortex is a project template, not a traditional application. A change to a script, configuration file, or workflow can affect every project that uses it. Because of this, Vortex uses a multi-layered testing approach to catch issues at different levels of integration before they reach consumers.

Unit testing

Bats is used to unit test the shell scripts shipped via the drevops/vortex-tooling Composer package (installed at vendor/drevops/vortex-tooling/src/). Each script is tested in isolation with external commands (like drush, docker, composer) replaced by mocks. This allows us to verify that individual scripts handle environment variables, flags, and edge cases correctly without needing a running Drupal site or Docker containers.

The bats-helpers library provides a step-based testing approach with built-in mocking and assertions, making it straightforward to define expected inputs and outputs for each script.

Unit tests execute in seconds, providing fast feedback during development. The test files in .vortex/tooling/tests/unit/ cover deployment, database operations, notifications, provisioning, and the other automation scripts - see Tooling > Testing for how to run them.

End-to-end testing

PHPUnit is used for functional end-to-end testing that exercises the full site build pipeline in real Docker containers. These tests simulate what a consumer site developer would experience: building containers, importing databases, running Drupal operations, linting code, and deploying artifacts.

The template end-to-end tests cover several critical workflows:

Docker Compose - building the container stack, verifying environment variables, running linters, executing PHPUnit and Behat tests inside containers, and checking Solr integration.
Ahoy workflows - testing the full developer experience through Ahoy commands, including build, login, Drush operations, Composer, database import/export, and code quality checks.
Deployment - testing deployment pipelines for artifact and webhook-based deployment strategies.

The phpunit-helpers library provides test helpers, traits, and assertions purpose-built for running shell commands and validating their output within PHPUnit tests.

End-to-end tests take minutes to run because they operate on real containers and a real Drupal site, and they verify that everything works together correctly.

Example site

The DrevOps website is a real-world production site built using Vortex. It serves as the final validation ground: if Vortex works correctly, the website should continue to build, test, and deploy without issues after each upstream update.

The website repository receives regular upstream updates from Vortex, including CI configuration, testing workflows, and infrastructure changes. This ensures that updates are validated against a real, long-lived codebase rather than just in test environments.

Running tests

Functional tests with PHPUnit

cd .vortex/tests

# Install Composer dependencies.
composer install

# Run all tests.
composer test

# Some tests require Composer and container registry tokens.
TEST_PACKAGE_TOKEN=<yourtoken> TEST_VORTEX_CONTAINER_REGISTRY_USER=<youruser> TEST_VORTEX_CONTAINER_REGISTRY_PASS=<yourpass> composer test

Functional tests rely on database fixtures - see the section below on updating test assets.

Unit tests with BATS

BATS unit tests for the shipped shell scripts live in .vortex/tooling/tests/unit/. Run them from .vortex/:

cd .vortex

# Run all BATS tests.
ahoy test-bats

# Run a single test file.
ahoy test-bats tooling/tests/unit/deploy.bats

➡️ See Tooling > Testing for the package's full test layers.

Updating test assets

There are demo and test database dumps captured as files and container images. All flows are automated by .vortex/tests/update-test-assets, which prints every shell command it runs.

php .vortex/tests/update-test-assets [mode] [--tag <tag>]

Without arguments, runs all for a full refresh. Default tag is latest.

Modes

Mode	What it does	Follow-up
`demo-dump`	Builds the demo profile in-place; exports `.data/db.demo.sql`.	Upload as `db.demo.sql` to the latest GitHub release.
`demo-image`	Builds the demo profile in-place; pushes `drevops/vortex-dev-mariadb-drupal-data-demo-11.x:<tag>`.	None.
`test-dump`	Installs Vortex into `/tmp/star-wars`; builds; exports `/tmp/star-wars/.data/db.test.sql`.	Upload as `db_d11.test.sql` to the latest GitHub release.
`test-image`	Installs Vortex into `/tmp/star-wars`; builds; pushes `drevops/vortex-dev-mariadb-drupal-data-test-11.x:<tag>`.	None.
`destination-images`	Tags and pushes the local demo image to the didi destination tags (`vortex-dev-database-ii`, `vortex-dev-didi-database-fi`).	None.
`all`	Optimized full refresh: builds the demo stack once for both demo modes and the test stack once for both test modes (2 stack builds instead of 4), then pushes images and tags destination images. Default when no mode is given.	Upload both dump files as above.

Options

Option	Description
`--tag <tag>`	Image tag for image modes. Default: `latest`. Also accepts `--tag=<tag>`.

Requirements

docker, ahoy, curl, sed, php available on PATH.
A Docker Hub session with push permission to drevops/ for any image mode.
The demo-image, test-image and all modes download seed.sh from a pinned drevops/mariadb-drupal-data release and verify it against a recorded SHA-256 checksum. Adopting a newer release is a manual step: update SEED_URL and SEED_SHA256 together.

Caveats

Demo modes are destructive against the current repository: containers are reset and .data/db.sql is removed before the rebuild.
Test modes wipe and recreate /tmp/star-wars on each run.
destination-images expects drevops/vortex-dev-mariadb-drupal-data-demo-11.x:latest to already exist locally - run demo-image (or all) first.

Examples

# Full refresh of every asset at :latest (default).
php .vortex/tests/update-test-assets

# Full refresh, tagging images as :rc1.
php .vortex/tests/update-test-assets --tag rc1

# Refresh only the test container image at :latest.
php .vortex/tests/update-test-assets test-image

# Refresh only the test container image at :rc1.
php .vortex/tests/update-test-assets test-image --tag rc1

Authoring scripts​

Requirements​

Variables​

Boilerplate script​

Testing​

Unit testing​

End-to-end testing​

Example site​

Running tests​

Functional tests with PHPUnit​

Unit tests with BATS​

Updating test assets​

Modes​

Options​

Requirements​

Caveats​

Examples​

Authoring scripts

Requirements

Variables

Boilerplate script

Testing

Unit testing

End-to-end testing

Example site

Running tests

Functional tests with PHPUnit

Unit tests with BATS

Updating test assets

Modes

Options

Requirements

Caveats

Examples