Continuous (Coldfusion) Integration with Testbox and Bitbucket Pipelines

The Continuous Integration (CI) guide for Coldfusion I wish I had two years ago.

If you don't know what Continuous Integration is, you should. Moving on!

Commandbox and Testbox Installation

So you'll need testbox installed and a test harness set up. First, install Commandbox if you don't already have it, then run

box

to drop into the Commandbox shell.

Then install Testbox:

install testbox

Duh, right? :)

Setup a "test harness" - e.g., the folder where your tests go. To do this, once you've installed testbox into your app you can simply copy the test-harness/ folder from /testbox to your app root:

cp testbox/test-harness .

Configure Testbox

I assume you already have a box.json file in your app root? If not, it won't hurt! Run box init to quickly set up a box.json.

Make sure your box.json file contains testbox config. Here's what mine looks like:

"testbox":{
        "bundles":"",
        "directory":"tests.specs",
        "labels":"",
        "options":{},
        "recurse":true,
        "reporter":"",
        "runner":[
                {
                        "default":"http://127.0.0.1:8010/tests/runner.cfm"
                }
        ],
        "testBundles":"",
        "testSpecs":"",
        "testSuites":"",
        "verbose":true,
        "watchDelay":500,
        "watchPaths":"**.cfc"
}

For more testbox configuration, see Testbox Gitlab docs or Testbox integration in Commandbox

Basic Bitbucket Pipelines setup

First, you'll need to enable Bitbucket Pipelines in your repository Pipelines settings.

Next, add a bitbucket-pipelines.yml file to your repository.

touch bitbucket-pipelines.yml

This is where you'll configure ... yeah, duh.

Here's what I used to run my tests. It's mostly copied from the Testbox documentation for Gitlab CI This is a pretty basic setup - in my case I needed to test against a database connection as well, so my setup was a little more complicated. (I've got a blog post coming about testing against a database connection.).

# Using the Commandbox Alpine image: https://hub.docker.com/r/ortussolutions/commandbox/
# Also see: https://testbox.ortusbooks.com/continuous-integration/gitlab
image: ortussolutions/commandbox:alpine

pipelines:
  default:
  - step:
       script:
          - box install production=true && box server start
          - box testbox run

Next, I added an optional name to my pipeline and specified deployment: test while I was at it. The name helps make your pipelines look a little cleaner in the web UI or notification emails, and the deployment option makes it more obvious what/where the app is being deployed to or for.

Note that we use production=true in the box install command to avoid installing development junk and slowing down our pipeline.

# Using the Commandbox Alpine image: https://hub.docker.com/r/ortussolutions/commandbox/
# Also see: https://testbox.ortusbooks.com/continuous-integration/gitlab
image: ortussolutions/commandbox:alpine

pipelines:
  default:
  - step:
       name: test
       deployment: test
       script:
          - box install production=true && box server start
          - box testbox run

To test the pipeline, you should only need to push your code / tests / bitbucket-pipelines.yml to Bitbucket, assuming you have Pipelines enabled.

git push

Debugging

  • The bitbucket-pipelines.yml config file is yaml, so make sure to get your indentation right!
  • Tabs not allowed, use spaces instead.
  • Bitbucket validates the bitbucket-pipelines.yml syntax on push and is pretty good about letting you know the difference between a failed pipeline and invalid syntax in the config file.
  • You can use the config validator for more advanced config, but be aware that the validator may not catch every syntax error, simply due to the nature of the environment.

Thank you for reading!

December 22, 2018

« Docker Compose Environments for Coldfusion Development - Testbox Caching in Bitbucket Pipelines »