Copyright Since 2005 TestBox by Luis Majano and Ortus Solutions, Corp
www.testbox.run | www.ortussolutions.com

TestBox - BDD/TDD Testing Framework for BoxLang & CFML

Professional BDD (Behavior-Driven Development) and TDD (Test-Driven Development) testing framework for BoxLang and CFML applications. TestBox provides a comprehensive testing ecosystem with integrated mocking capabilities, multiple output formats, and both CLI and web-based test runners.

🌟 Features

• Dual Testing Approaches: Full support for both BDD (describe(), it()) and xUnit (setup(), test*()) styles
• BoxLang First: Native support for BoxLang with dedicated CLI runner, plus full CFML compatibility
• Integrated Mocking: Built-in MockBox framework with spies, stubs, and verification capabilities
• Rich Data Generation: CBMockData integration for realistic test data (names, addresses, dates)
• Multiple Reporters: 15+ output formats including HTML, JSON, XML, TAP, JUnit, and Console
• CLI & Web Runners: Execute tests via CommandBox CLI or web-based interfaces
• File Watching: Automatic test re-execution on code changes during development
• Code Coverage: Built-in coverage analysis and reporting
• Flexible Discovery: Automatic test bundle detection with customizable patterns
• Thread-Safe: Concurrent test execution with proper isolation

💻 Requirements

• BoxLang: 1.0+
• Lucee: 6.0+
• Adobe ColdFusion: 2023+

⚡ Quick Start

1. Installation

# Install TestBox and CLI tools via CommandBox
box install testbox testbox-cli

# Or install bleeding edge
box install testbox@be testbox-cli

2. Create Your First Test

// tests/specs/UserServiceTest.cfc
class extends="testbox.system.BaseSpec" {

    function run() {
        describe( "UserService", () => {
            beforeEach( () => {
                userService = new models.UserService()
            } )

            it( "should create a new user", () => {
                var user = userService.createUser( "[email protected]", "John Doe" )
                expect( user.getEmail() ).toBe( "[email protected]" )
                expect( user.getName() ).toBe( "John Doe" )
            } )
        } )
    }
}

🎭 MockBox Integration & Test Data

Advanced Mocking with MockBox

class extends="testbox.system.BaseSpec" {

    function run() {
        describe( "Payment Service", () => {
            beforeEach( () => {
                // Create mocks and spies
                mockGateway = createMock( "services.PaymentGateway" )
                mockLogger = createEmptyMock( "cblogger.models.Logger" )

                // Setup mock behavior
                mockGateway.$( "processPayment" ).$results( {
                    success: true,
                    transactionId: "TXN-12345"
                } )

                paymentService = new models.PaymentService(
                    gateway = mockGateway,
                    logger = mockLogger
                )
            } )

            it( "should process payment and log success", () => {
                var result = paymentService.charge( 100.00, "USD" )

                // Verify method calls
                expect( mockGateway.$times( 1, "processPayment" ) ).toBeTrue()
                expect( mockLogger.$times( 1, "info" ) ).toBeTrue()

                // Verify results
                expect( result.success ).toBeTrue()
                expect( result.transactionId ).toBe( "TXN-12345" )
            } )
        } )
    }
}

Realistic Test Data with CBMockData

class extends="testbox.system.BaseSpec" {

    function run() {
        describe("User Profile Tests", () => {
            it("should handle various user data scenarios", () => {
                // Generate realistic test data
                var testUsers = mockData(
					firstName = "fname",
					lastName = "lname",
					email = "email",
					age = "age",
					address = {
						street = "streetaddress",
						city = "city",
						state = "state",
						zipCode = "zipcode"
					},
					registrationDate = "datetime"
				)

                // Test with realistic data
                for ( var user in testUsers ) {
                    var profile = userService.createProfile( user )
                    expect( profile.isValid() ).toBeTrue()
                    expect( profile.getEmail() ).toMatch( "^[\w\.-]+@[\w\.-]+\.[A-Za-z]{2,}$" )
                }
            })
        })
    }
}

3. Run Your Tests

# Via CommandBox CLI
box testbox run

# Via BoxLang CLI Runner (fastest execution)
./testbox/run                           # Run default tests.specs
./testbox/run --directory=my.tests      # Specific directory
./testbox/run --bundles=my.bundle       # Specific bundles
./testbox/run --reporter=json           # Custom reporter

# Via web browser
# Navigate to: http://localhost/testbox/system/runners/HTMLRunner.cfm

🧪 Testing Approaches

BDD Style (Behavior-Driven Development)

class extends="testbox.system.BaseSpec" {

    function run() {
        describe( "User Registration", () => {
            beforeEach(() => {
                userService = createMock("models.UserService")
                variables.sut = new handlers.Users()
            })

            describe("When registering a new user", () => {
                it("should validate email format", () => {
                    expect(() => {
                        userService.register("invalid-email", "password")
                    }).toThrow("ValidationException")
                })

                it("should create user with valid data", () => {
                    var result = userService.register("[email protected]", "securePass")
                    expect(result.success).toBeTrue()
                    expect(result.user.email).toBe("[email protected]")
                })
            })
        })
    }
}

xUnit Style (Traditional Unit Testing)

class extends="testbox.system.BaseSpec" {

    function setup() {
        // Runs before each test
        userService = new models.UserService()
        testData = {
            email: "[email protected]",
            name: "Test User"
        }
    }

    function testUserCreation() {
        var user = userService.createUser( testData.email, testData.name )
        $assert.isEqual( testData.email, user.getEmail() )
        $assert.isEqual( testData.name, user.getName() )
    }

    function testEmailValidation() {
        $assert.throws( () => {
            userService.createUser( "invalid-email", "Test User" )
        }, "ValidationException" )
    }

    function tearDown() {
        // Cleanup after each test
        structDelete( variables, "userService" )
        structDelete( variables, "testData" )
}

⚙️ Configuration & CLI Usage

CLI Test Execution

# Run all tests with default settings
box testbox run

# Run specific test bundles
box testbox run bundles=tests.specs.UserServiceTest

# Run tests with custom reporter
box testbox run reporter=json

# Run tests with labels ( focused testing )
box testbox run labels=unit --excludes=integration

# Watch mode for continuous testing
box testbox watch

# Generate test templates
box testbox create bdd MyNewTest
box testbox create unit MyNewTest

Application Setup

Create an Application.bx|cfc in your test directory:

class {
	// Test application name
    this.name = "MyApp-Tests"

    // TestBox mappings
    this.mappings[ "/testbox" ] = expandPath( "/testbox" );
    this.mappings[ "/tests" ] = getDirectoryFromPath( getCurrentTemplatePath() );
    this.mappings[ "/models" ] = expandPath( "/models" );

}

Web Runner Configuration

Create tests/runner.bxm|cfm for web-based test execution:

<!DOCTYPE html>
<html>
<head>
    <title>My Application Test Suite</title>
</head>
<body>
    <bx:script>
        // Create TestBox instance
        testbox = new testbox.system.TestBox(
            options = {
                // Test bundle directories
                bundles = [
                    "tests.specs"
                ],
                // Directories to include/exclude
                directory = {
                    mapping = "tests.specs",
                    recurse = true
                },
                // Test labels
                labels = url.labels ?: "",
                excludes = url.excludes ?: "",
                // Reporter
                reporter = url.reporter ?: "simple",
                // Coverage settings
                coverage = {
                    enabled = true,
                    pathToCapture = expandPath("/models"),
                    whitelist = "*.cfc",
                    blacklist = "*Test*.cfc"
                }
            }
        )

        // Run tests and output results
        writeOutput( testbox.run() )
    </bx:script>
</body>
</html>

📄 License

Apache License, Version 2.0.

📋 Versioning

TestBox is maintained under the Semantic Versioning guidelines as much as possible.

Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)
• New additions without breaking backward compatibility bumps the minor (and resets the patch)
• Bug fixes and misc changes bumps the patch

📚 Documentation & Resources

Source Code

• GitHub Repository

Bug Tracking

• Issue Tracker

Community & Support

• Community Forum
• Join BoxTeam Slack

Official Documentation

• TestBox Documentation
• BDD Primer
• xUnit Primer

Community and Support

Join us in our Ortus Community and become a valuable member of this project TestBox BDD. We are looking forward to hearing from you!!

Official Sites

• TestBox Official Site
• Ortus Solutions

📄 License

Apache License, Version 2.0. See LICENSE file for details.

---

About Ortus Solutions

TestBox is a professional open-source project by Ortus Solutions.

• TestBox Framework: https://www.testbox.run
• Ortus Solutions: https://www.ortussolutions.com

---

Copyright Since 2005 TestBox by Luis Majano and Ortus Solutions, Corp

www.testbox.run | www.ortussolutions.com

---

✝️ HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us." Romans 5:5

🍞 THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" John 14:1-12