wheels test run

Run TestBox tests for your application with advanced features.

Synopsis

wheels test run [spec] [options]

Description

The wheels test run command executes your application's TestBox test suite with support for watching, filtering, and various output formats. This is the primary command for running your application tests (as opposed to framework tests).

Arguments

Argument	Description	Default
spec	Specific test spec or directory	All tests

Options

Option	Description	Default
--watch	Watch for changes and rerun	false
--reporter	TestBox reporter	simple
--recurse	Recurse directories	true
--bundles	Test bundles to run
--labels	Filter by labels
--excludes	Patterns to exclude
--filter	Test name filter
--outputFile	Output results to file
--verbose	Verbose output	false
--help	Show help information

Examples

Run all tests

wheels test run

Run specific test file

wheels test run tests/models/UserTest.cfc

Run tests in directory

wheels test run tests/controllers/

Watch mode

wheels test run --watch

Run specific bundles

wheels test run --bundles=models,controllers

Filter by labels

wheels test run --labels=unit,critical

Use different reporter

wheels test run --reporter=json
wheels test run --reporter=junit
wheels test run --reporter=text

Save results to file

wheels test run --reporter=junit --outputFile=test-results.xml

Test Structure

Standard test directory layout:

/tests/
├── Application.cfc      # Test configuration
├── models/             # Model tests
│   ├── UserTest.cfc
│   └── ProductTest.cfc
├── controllers/        # Controller tests
│   ├── UsersTest.cfc
│   └── ProductsTest.cfc
├── views/             # View tests
├── integration/       # Integration tests
└── helpers/          # Test helpers

Writing Tests

Model Test Example

component extends="testbox.system.BaseSpec" {

    function run() {
        describe("User Model", function() {
            
            beforeEach(function() {
                // Reset test data
                application.wirebox.getInstance("User").deleteAll();
            });
            
            it("validates required fields", function() {
                var user = model("User").new();
                expect(user.valid()).toBeFalse();
                expect(user.errors).toHaveKey("email");
                expect(user.errors).toHaveKey("username");
            });
            
            it("saves with valid data", function() {
                var user = model("User").new(
                    email="[e-mail]",
                    username="testuser",
                    password="secret123"
                );
                expect(user.save()).toBeTrue();
                expect(user.id).toBeGT(0);
            });
            
            it("prevents duplicate emails", function() {
                var user1 = model("User").create(
                    email="[e-mail]",
                    username="user1"
                );
                
                var user2 = model("User").new(
                    email="[e-mail]",
                    username="user2"
                );
                
                expect(user2.valid()).toBeFalse();
                expect(user2.errors.email).toContain("already exists");
            });
            
        });
    }

}

Controller Test Example

component extends="testbox.system.BaseSpec" {

    function run() {
        describe("Products Controller", function() {
            
            it("lists all products", function() {
                // Create test data
                var product = model("Product").create(name="Test Product");
                
                // Make request
                var event = execute(
                    event="products.index",
                    renderResults=true
                );
                
                // Assert response
                expect(event.getRenderedContent()).toInclude("Test Product");
                expect(event.getValue("products")).toBeArray();
            });
            
            it("requires auth for create", function() {
                var event = execute(
                    event="products.create",
                    renderResults=false
                );
                
                expect(event.getValue("relocate_URI")).toBe("/login");
            });
            
        });
    }

}

Test Configuration

/tests/Application.cfc

component {
    this.name = "WheelsTestingSuite" & Hash(GetCurrentTemplatePath());
    
    // Use test datasource
    this.datasources["wheelstestdb"] = {
        url = "jdbc:h2:mem:wheelstestdb;MODE=MySQL"
    };
    this.datasource = "wheelstestdb";
    
    // Test settings
    this.testbox = {
        testBundles = "tests",
        recurse = true,
        reporter = "simple",
        labels = "",
        options = {}
    };
}

Watch Mode

Watch mode reruns tests on file changes:

wheels test run --watch

Output:

[TestBox Watch] Monitoring for changes...
[TestBox Watch] Watching: /tests, /models, /controllers

[14:23:45] Change detected: models/User.cfc
[14:23:45] Running tests...

✓ User Model > validates required fields (12ms)
✓ User Model > saves with valid data (45ms)
✓ User Model > prevents duplicate emails (23ms)

Tests: 3 passed, 0 failed
Time: 80ms

[TestBox Watch] Waiting for changes...

Reporters

Simple (Default)

wheels test run --reporter=simple

• Colored console output

• Shows progress dots

• Summary at end

Text

wheels test run --reporter=text

• Plain text output

• Good for CI systems

• No colors

JSON

wheels test run --reporter=json

{
    "totalDuration": 523,
    "totalSpecs": 25,
    "totalPass": 24,
    "totalFail": 1,
    "totalError": 0,
    "totalSkipped": 0
}

JUnit

wheels test run --reporter=junit --outputFile=results.xml

• JUnit XML format

• For CI integration

• Jenkins compatible

TAP

wheels test run --reporter=tap

• Test Anything Protocol

• Cross-language format

Filtering Tests

By Bundle

# Run only model tests
wheels test run --bundles=models

# Run multiple bundles
wheels test run --bundles=models,controllers

By Label

it("can authenticate", function() {
    // test code
}).labels("auth,critical");

# Run only critical tests
wheels test run --labels=critical

# Run auth OR api tests
wheels test run --labels=auth,api

By Name Filter

# Run tests matching pattern
wheels test run --filter="user"
wheels test run --filter="validate*"

Exclude Patterns

# Skip slow tests
wheels test run --excludes="*slow*,*integration*"

Parallel Execution

Run tests in parallel threads:

wheels test run --threads=4

Benefits:

• Faster execution

• Better CPU utilization

• Finds concurrency issues

Code Coverage

Generate coverage reports:

wheels test run --coverage --coverageOutputDir=coverage/

View report:

open coverage/index.html

Test Helpers

Create reusable test utilities:

// /tests/helpers/TestHelper.cfc
component {
    
    function createTestUser(struct overrides={}) {
        var defaults = {
            email: "test#CreateUUID()#@example.com",
            username: "user#CreateUUID()#",
            password: "testpass123"
        };
        
        return model("User").create(
            argumentCollection = defaults.append(arguments.overrides)
        );
    }
    
    function loginAs(required user) {
        session.userId = arguments.user.id;
        session.isAuthenticated = true;
    }
    
}

Database Strategies

Transaction Rollback

function beforeAll() {
    transaction action="begin";
}

function afterAll() {
    transaction action="rollback";
}

Database Cleaner

function beforeEach() {
    queryExecute("DELETE FROM users");
    queryExecute("DELETE FROM products");
}

Fixtures

function loadFixtures() {
    var users = deserializeJSON(
        fileRead("/tests/fixtures/users.json")
    );
    
    for (var userData in users) {
        model("User").create(userData);
    }
}

CI/CD Integration

GitHub Actions

- name: Run tests
  run: |
    wheels test run --reporter=junit --outputFile=test-results.xml
    
- name: Upload results
  uses: actions/upload-artifact@v2
  with:
    name: test-results
    path: test-results.xml

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Running tests..."
wheels test run --labels=unit

if [ $? -ne 0 ]; then
    echo "Tests failed. Commit aborted."
    exit 1
fi

Performance Tips

1. Use labels for fast feedback

   wheels test run --labels=unit  # Fast
   wheels test run --labels=integration  # Slow

2. Parallel execution

   wheels test run --threads=4

3. Watch specific directories

   wheels test run tests/models --watch

4. Skip slow tests during development

   wheels test run --excludes="*integration*"

Common Issues

Out of Memory

# Increase memory
box server set jvm.heapSize=1024
box server restart

Test Pollution

• Use beforeEach/afterEach

• Reset global state

• Use transactions

Flaky Tests

• Avoid time-dependent tests

• Mock external services

• Use fixed test data

See Also

• wheels test - Run framework tests
• wheels test coverage - Generate coverage
• wheels test debug - Debug tests
• wheels generate test - Generate test files