Testing & Debugging CFML

Debugging and testing — two tools every CF developer needs

Writing code that works once in a happy path is easy. Writing code that keeps working as requirements change, that fails clearly when something is wrong, and that you can fix quickly when it breaks — that requires two disciplines: debugging and testing.

Debugging is how you understand what your code is actually doing right now. ColdFusion gives you cfdump, cflog, and the CF Admin debugger — tools that let you inspect any variable, trace execution, and read structured log entries without touching production.

Testing is how you prove your code does what it should — and keep proving it every time you change something. ColdFusion's testing ecosystem is built around TestBox, the de-facto standard BDD/TDD framework for CFML, built by Ortus Solutions and documented at testbox.ortusbooks.com.

In this lesson you will:

1. Use cfdump to inspect live data structures in the browser
2. Write structured log entries with cflog and read them from the terminal
3. Install TestBox and write a test spec against the TicketService already running in your lab
4. Run the test suite and verify it passes

Who does this? Debugging tools are used by every developer daily. Unit testing is a developer responsibility — not something reserved for QA. In a well-run team, tests live alongside the code and run on every commit.

1. Debugging with cfdump

cfdump renders any ColdFusion variable as a colour-coded HTML table — the fastest way to inspect data during development.

<cfset data = {name: "Alex", scores: [95, 87, 72]}>
<cfdump var="#data#" label="Student data">

cfdump renders any CF variable as a colour-coded interactive table — the fastest debugging tool in CFML.

Useful cfdump attributes:

grep -r "cfdump" /opt/coldfusion2025/cfusion/wwwroot/

2. Logging with cflog

cflog writes structured entries to a named log file in CF's log directory — visible in the terminal without touching the browser.

<cflog file="training" text="Processing ticket #url.id#"    type="information">
<cflog file="training" text="Ticket not found: #url.id#"    type="warning">
<cflog file="training" text="DB error: #cfcatch.message#"   type="error">
<cflog file="training" text="Server shutting down"          type="fatal">

cflog attributes:

The file attribute sets the log filename — CF creates the file automatically on the first write. It will not exist until at least one cflog call has executed. Once it does, you can tail it live:

tail -f /opt/coldfusion2025/cfusion/logs/training.log

The log format includes a timestamp, thread ID, severity, and your message — structured and grep-friendly.

tail: cannot open '.../training.log' for reading: No such file or directory
tail: no files remaining

sudo tee -a /opt/coldfusion2025/cfusion/wwwroot/debug-demo.cfm << 'EOF'
<cflog file="training" text="test entry from debug-demo.cfm" type="information">
EOF

curl -s http://localhost:8500/debug-demo.cfm > /dev/null

tail -f /opt/coldfusion2025/cfusion/logs/training.log

tail -F /opt/coldfusion2025/cfusion/logs/training.log

3. TestBox — unit testing for CFML

TestBox is the de-facto standard testing framework for CFML, built and maintained by Ortus Solutions. It is open source, actively maintained, and the framework you will encounter on almost every serious CFML project.

Full documentation: testbox.ortusbooks.com

curl "http://localhost:8888/testbox/system/runners/StreamingRunner.cfm?directory=tests"

TestBox BDD structure: describe groups related tests, it defines one behaviour, expect asserts the outcome.

Install TestBox

TestBox installs into your student app directory via CommandBox:

cd ~/app
box install testbox

This downloads TestBox into ~/app/testbox/ and makes the test runner available at http://localhost:8888/testbox/.

box install testbox pulls TestBox and its dependencies from ForgeBox. The "Initializing libraries" message only appears on the first run — subsequent installs are faster.

What TicketService does

Before writing the spec, understand what you are testing. TicketService.cfc in ~/app/ is a service CFC that queries the hd_tickets table in the Lucee-side H2 database. It exposes two methods:

The beforeAll block in the test spec calls seed-db.cfm via cfhttp to populate the in-memory H2 database before any test runs. Without that seed call, getAll() returns an empty array and getById(1) returns nothing — both tests would fail.

# Verify TicketService and seed-db.cfm exist in ~/app/
ls ~/app/TicketService.cfc ~/app/seed-db.cfm

Write a test spec

Create the tests directory and spec file:

mkdir -p ~/app/tests
tee ~/app/tests/TicketServiceTest.cfc << 'EOF'
component extends="testbox.system.BaseSpec" {

  function run() {

    describe("TicketService", function() {

      // Seed the database once before the tests are defined.
      // This TestBox version only has beforeEach/afterEach — no beforeAll.
      // Calling cfhttp here runs once when the describe closure is executed.
      cfhttp(url="http://localhost:8888/seed-db.cfm", method="GET");

      var svc = new TicketService();

      it("should return all tickets as an array", function() {
        var result = svc.getAll();
        expect(result).toBeArray();
        expect(arrayLen(result)).toBeGTE(1);
      });

      it("should return a single ticket by id", function() {
        var ticket = svc.getById(1);
        expect(ticket).toBeStruct();
        expect(ticket).toHaveKey("title");
      });

    });

  }
}
EOF

Anatomy of a TestBox spec: each part has a specific role — understand the structure before running the suite.

What each line does:

Run the tests

Hit the StreamingRunner with curl — plain text output, no interactive CLI, no hanging:

curl -s "http://localhost:8888/testbox/system/runners/StreamingRunner.cfm?directory=tests"

A passing suite ends with:

Tests: 2 Passed: 2 Failed: 0 Errors: 0 Skipped: 0

A failing test shows exactly which it() block failed and why:

[FAIL] TicketService > should return all tickets as an array
  Expected [] to have a length greater than or equal to 1
  >> Did you forget to run seed-db.cfm in beforeAll?

4. CF Admin Debugger

For deeper request-level tracing, ColdFusion's built-in debugger appends a full diagnostic panel to every rendered page — showing SQL queries executed, their execution times, template load times, and variable scopes.

Enable it in CF Admin:

1. Open CF Admin → Debugging & Logging → Debug Output Settings
2. Check Enable Request Debugging Output
3. Add 127.0.0.1 to the IP address restriction list so only your terminal sees the output

Debugging output appears at the bottom of every CF page response. It is automatically hidden from any IP not on the list — safe to leave enabled in the lab, but always disable it before any public deployment.

Activity 1 — Inspect data with cfdump

Create a page that dumps a struct and array so you can see cfdump in action:

sudo tee /opt/coldfusion2025/cfusion/wwwroot/debug-demo.cfm << 'EOF'
<cfscript>
  ticket = {
    id:       1,
    title:    "Cannot connect to VPN",
    status:   "open",
    priority: "high",
    tags:     ["network", "remote", "urgent"]
  };
</cfscript>

<cfdump var="#ticket#" label="Sample ticket struct">
EOF

Open the ColdFusion browser tab and navigate to /debug-demo.cfm. You should see the colour-coded dump table with the nested tags array expanded inline.

Activity 2 — Write a log entry and read it

Add a cflog call to your debug page and tail the log file:

sudo tee -a /opt/coldfusion2025/cfusion/wwwroot/debug-demo.cfm << 'EOF'
<cflog file="training" text="debug-demo.cfm loaded by #cgi.REMOTE_ADDR#" type="information">
EOF

Now tail the log in a second terminal tab while you refresh the page:

tail -f /opt/coldfusion2025/cfusion/logs/training.log

Each page load should add a new timestamped line to the log.

Activity 3 — Install TestBox and write a test spec

First, verify the files TestBox will test are in place:

ls ~/app/TicketService.cfc ~/app/seed-db.cfm ~/app/Application.cfc

All three must exist. If any are missing, see the hint boxes below before continuing.

Install TestBox into your student app:

cd ~/app && box install testbox

Then create the spec:

mkdir -p ~/app/tests
tee ~/app/tests/TicketServiceTest.cfc << 'EOF'
component extends="testbox.system.BaseSpec" {

  function run() {

    describe("TicketService", function() {

      // Seed the database once before the tests are defined.
      // This TestBox version only has beforeEach/afterEach — no beforeAll.
      // Calling cfhttp here runs once when the describe closure is executed.
      cfhttp(url="http://localhost:8888/seed-db.cfm", method="GET");

      var svc = new TicketService();

      it("should return all tickets as an array", function() {
        var result = svc.getAll();
        expect(result).toBeArray();
        expect(arrayLen(result)).toBeGTE(1);
      });

      it("should return a single ticket by id", function() {
        var ticket = svc.getById(1);
        expect(ticket).toBeStruct();
        expect(ticket).toHaveKey("title");
      });

    });

  }
}
EOF

Activity 4 — Run the tests

curl -s "http://localhost:8888/testbox/system/runners/StreamingRunner.cfm?directory=tests"

All tests must pass — zero failures, zero errors.

ls ~/app/testbox/system/runners/

cd ~/app && box install testbox

grep -n "function before\|function after\|function setUp\|function setup" ~/app/testbox/system/BaseSpec.cfc | head -20

describe("TicketService", function() {
  // Runs once when TestBox processes this describe block — no lifecycle hook needed
  cfhttp(url="http://localhost:8888/seed-db.cfm", method="GET");

  it("should ...", function() { ... });
});

curl -s http://localhost:8888/seed-db.cfm

curl -s -o /dev/null -w "%{http_code}" http://localhost:8888/

ls ~/app/seed-db.cfm

cat ~/app/Application.cfc

component {
  this.name = "cfTrainingApp";

  this.datasources["training_db"] = {
    class:            "org.h2.Driver",
    connectionString: "jdbc:h2:mem:training_db;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE",
    username:         "sa",
    password:         ""
  };
}

tee ~/app/Application.cfc << 'EOF'
component {
  this.name = "cfTrainingApp";

  this.datasources["training_db"] = {
    class:            "org.h2.Driver",
    connectionString: "jdbc:h2:mem:training_db;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE",
    username:         "sa",
    password:         ""
  };
}
EOF
cd ~/app && box server restart

Further reading

• TestBox documentation — testbox.ortusbooks.com — full reference for matchers, mocking, reporters, and CI integration
• ForgeBox — forgebox.io/view/testbox — package listing, version history, changelog
• Ortus Solutions blog — www.ortussolutions.com/blog — tutorials and TestBox release announcements
• ColdFusion docs — cflog — helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-j-l/cflog.html
• ColdFusion docs — cfdump — helpx.adobe.com/coldfusion/cfml-reference/coldfusion-tags/tags-d-e/cfdump.html

When all the checks above are green, this lesson is complete. Your progress is saved automatically — move straight on to the next lesson.