Downloads

Download ColdFusion Unit Testing Starter (TestBox)

by Aaron Longnion
7 min read

Get a head start on automated testing for your CFML applications with a ready-to-run TestBox starter. This downloadable resource gives you a clean, opinionated scaffold for writing, running, and automating unit and Integration tests across Lucee and Adobe ColdFusion. Whether you’re new to TestBox or migrating an existing app to a CI/CD pipeline, this starter accelerates setup, helps enforce good testing practices, and integrates seamlessly with CommandBox.

The package includes a conventional folder structure, example specs, CommandBox tasks, and a browser-friendly TestBox runner. You can run tests in a browser or from the command line with reporting suitable for local development and continuous Integration.

Contents show

Overview

The ColdFusion Unit testing Starter (TestBox) is a lightweight bootstrap project designed to help CFML teams adopt TDD/BDD testing quickly. It comes preconfigured with TestBox, optional MockBox usage, and a CommandBox-powered server so you can start testing in minutes. It works with both Lucee and Adobe ColdFusion, and it’s suitable for standalone CFML apps, ColdBox modules, and legacy codebases being retrofitted with tests.

Key goals:

  • Provide a minimal yet complete test harness.
  • Offer CLI and browser runners.
  • Support CI pipelines (GitHub Actions, GitLab CI, Jenkins, Azure DevOps).
  • Encourage clean test organization and fast feedback.

What You’ll Get

Inside the Download, you’ll find a curated set of files and directories so you can immediately run TestBox and start writing specifications.

  • README.md

    • A quick guide to running your first tests and customizing the setup.

  • box.json

    • CommandBox metadata for dependencies and scripts. Includes TestBox as a dependency and prebuilt scripts for running tests.

  • server.json

    • Preconfigured CommandBox server with a default cfengine (Lucee). Easily switch to Adobe ColdFusion if needed.

  • Application.cfc (root) and tests/Application.cfc

    • Sensible defaults for test isolation and Request handling in both app and test scopes.

  • tests/

    • runner.cfm — Browser-based TestBox runner.
    • resources/ — Fixtures, sample data, and helpers.
    • specs/
      • ExampleSpec.cfc — Demonstrates expectations, setup/teardown, and matchers.
      • ServiceSpec.cfc — Shows patterns for unit vs. integration test boundaries.

  • src/

    • Minimal example components under test (CFCs) to illustrate structure.

  • .env.example

    • Example environment variables for DB credentials, API keys, or feature flags.

  • .gitignore

    • Recommended ignores for CFML, CommandBox artifacts, and temporary files.
See also  Download the Complete ColdFusion Security Checklist (PDF)

Optional integrations (commented or documented in README):

  • CBWIRE/ColdBox hints for Modular apps.
  • MockBox usage in test specs.
  • Coverage addon suggestion (cbcoverage) for code coverage reports.

Supported Environments

  • CF Engines:
    • Lucee 5.x and 6.x
    • Adobe ColdFusion 2018, 2021, 2023
  • Operating Systems:
    • Windows, macOS, Linux
  • CLI:
    • CommandBox 5.x or later
  • CI Platforms:
    • GitHub Actions, GitLab CI, Jenkins, Azure DevOps, CircleCI
  • Containers:
    • Docker images for Lucee/Adobe CF via CommandBox base images

Benefits

  • Zero-friction setup: Get testing without wrestling config.
  • Consistent structure: Clear separation of src and tests speeds Onboarding.
  • Run anywhere: Browser runner for exploration; CLI for Automation.
  • CI-ready: Opinionated scripts and reporters tailored for pipelines.
  • Better Code quality: Encourages TDD/BDD, mocks/stubs, and small, testable units.
  • Adaptable: Works with standalone CFML apps and frameworks like ColdBox.

How to Install and Configure

Prerequisites

  • Java JRE/JDK installed and on PATH.
  • CommandBox installed.
  • Internet access to install dependencies the first time.

Quick Start

  1. Download and extract the “ColdFusion Unit testing Starter (TestBox)” zip into your project folder.

  2. Open a terminal in the project root and install dependencies:

  • box install
  1. Start a development server:
  • box server start
  1. Open the browser runner:
  1. Run tests from the CLI (headless):
  • box testbox run
  • box testbox run –reporter=json
  • box testbox run –watch (re-runs tests on file changes)

Switching Engines (Lucee ↔ Adobe ColdFusion)

  1. Open server.json in the project root.

  2. Change the cfengine value:

  • For Lucee: “cfengine”: “lucee@5.4.4+38”
  • For Adobe 2023: “cfengine”: “adobe@2023”
  1. Restart the server:
  • box server stop
  • box server start

Configuration Highlights

  • Environment variables:
    • Copy .env.example to .env and set secrets for integration tests.
  • Test Configuration:
    • tests/Application.cfc isolates test app settings (mappings, request timeouts, etc.).
  • TestBox runner:
    • tests/runner.cfm supports reporters like simple, json, text, and junit.
    • CLI reporter flags map to CI-friendly formats.
See also  Download ColdFusion Health Check & Status Endpoint Example

How to Use the Starter

Writing Your First Spec

  1. Create a CFC under src/, for example src/utils/Math.cfc with a function add(a,b).

  2. Add a new spec under tests/specs/, e.g., MathSpec.cfc:

  • Use describe/it blocks to group and define expectations.
  • Use beforeEach/afterEach to set up clean test state.
  1. Run your tests:
  • Browser: /tests/runner.cfm
  • CLI: box testbox run

Tip: Keep test names expressive and behavior-driven, e.g., “it should add two positive integers.”

Using MockBox (Stubs/Mocks)

  • Import MockBox inside your spec to isolate dependencies.
  • Stub external calls (database, HTTP) and focus on the unit under test.
  • Example patterns included in ServiceSpec.cfc so you can copy/paste to get started.

Benefits:

  • Deterministic tests that don’t rely on live services.
  • Accelerates feedback and supports TDD.

Integration vs. Unit Tests

  • Unit tests:
    • Validate a single CFC or function in isolation.
    • Use mocks/stubs for collaborators.
  • Integration tests:
    • Exercise multiple components together (e.g., service + DAO).
    • May read from test databases or fixtures (configurable via .env).

Recommendation:

  • Start with unit tests for core logic.
  • Add targeted integration tests for key workflows and persistence layers.

Optional: Code Coverage

  • Install the cbcoverage module if you need coverage metrics.
  • Configure coverage to include src/ and exclude tests/, vendors, and framework internals.
  • Run coverage in CI to enforce minimum thresholds.

Best practices

  • Keep tests small, fast, and independent.
  • Follow a clear folder structure: src/ mirrors tests/specs/.
  • Use given/when/then naming in specs to describe behavior.
  • Prefer pure functions and dependency injection to simplify testing.
  • Avoid global state; use setup/teardown hooks for test isolation.
  • Run tests locally via CLI before pushing to avoid flaky CI failures.
  • Tag slow or integration tests (e.g., @integration) and run them separately when needed.
  • Store secrets in .env, not in code or Version control.

CI/CD Integration

GitHub Actions (example steps)

  • actions/setup-java to install Java
  • Install CommandBox (script or action)
  • Commands:
    • box install
    • box testbox run –reporter=junit –output results.xml
  • Upload artifacts and publish test reports.

Jenkins

  • Use a pipeline stage with a Linux agent.
  • Install Java and CommandBox on the agent.
  • Run:
    • box install
    • box testbox run –reporter=junit –output results.xml
  • Use JUnit plugin to display results.
See also  Download ColdFusion Dockerfile and CommandBox Starter Pack

Containers (Docker)

  • Base on CommandBox images for Lucee or Adobe CF.
  • COPY your project, then:
    • box install
    • box testbox run
  • Map volumes for faster Iteration in local dev.

Use Cases

  • Greenfield projects adopting TDD/BDD from day one.
  • Legacy CFML apps adding tests incrementally without major rewrites.
  • Teams standardizing on CI pipelines for multi-engine testing (matrix builds).
  • Libraries/modules that need a repeatable, engine-agnostic test harness.
  • Onboarding new developers with a low-friction testing template.

Pros and cons

Pros:

  • Rapid setup with sensible defaults.
  • Compatible with Lucee and Adobe ColdFusion.
  • Works locally, in CI, and in containers.
  • Clear examples for unit and integration tests.

Cons:

  • Coverage requires an additional module (optional).
  • Advanced enterprise setups may still need customization (datasources, Security).

Key Takeaways

  • The starter provides a battle-tested TestBox harness that runs on Lucee and Adobe ColdFusion via CommandBox.
  • You can run tests in a browser or headless with CI-friendly reporters.
  • Opinionated structure and examples help teams write clean, maintainable specs quickly.
  • Optional patterns (MockBox, coverage, CI templates) ensure Scalability as your test suite grows.

FAQ

How do I run only a subset of tests?

Use TestBox tags or directories. For example:

  • box testbox run specPath=tests/specs/utils
  • Add @unit or @integration tags to your specs and use filters: box testbox run labels=unit

Can I use this with ColdBox applications?

Yes. The structure works for standalone CFML or ColdBox modules. Map your ColdBox conventions in tests/Application.cfc as needed, and point specs at your handlers/services.

How do I change to Adobe ColdFusion for testing?

Edit server.json and set cfengine to adobe@2023 (or your required version). Restart the server with:

  • box server stop
  • box server start

How do I integrate with GitHub Actions?

Install Java and CommandBox in your workflow, then run:

  • box install
  • box testbox run –reporter=junit –output results.xml
    Upload the results file or parse it with the test report action.

Do I need Docker to use this starter?

No. Docker is optional. You can run everything locally with CommandBox. If you do use containers, base images exist for both Lucee and Adobe CF to streamline CI/CD builds.

About the author

Aaron Longnion

Aaron Longnion

Hey there! I'm Aaron Longnion — an Internet technologist, web software engineer, and ColdFusion expert with more than 24 years of experience. Over the years, I've had the privilege of working with some of the most exciting and fast-growing companies out there, including lynda.com, HomeAway, landsofamerica.com (CoStar Group), and Adobe.com.

I'm a full-stack developer at heart, but what really drives me is designing and building internet architectures that are highly scalable, cost-effective, and fault-tolerant — solutions built to handle rapid growth and stay ahead of the curve.

View all posts

You may also like