Testing

Test your BoxLang module with TestBox and integrate testing into your CI/CD pipeline

Test your module using TestBox for BoxLang code, JUnit for Java code, or a combination of both.

TestBox Testing

TestBox is BoxLang's testing framework. Place tests in your module's tests/ directory.

Test Structure

my-module/
├── tests/
│   ├── Application.bx        # TestBox test harness
│   ├── specs/
│   │   ├── MyBIFTest.bx      # BDD-style tests
│   │   └── MyComponentTest.bx
│   └── resources/
│       └── fixtures/

BDD-Style Test Example

File: tests/specs/GreetBIFTest.bx

describe( "Greet BIF", () => {
    beforeEach( () => {
        variables.result = greet( "World" )
    } )

    it( "returns a greeting string", () => {
        expect( variables.result ).toBeString()
    } )

    it( "includes the name in the greeting", () => {
        expect( variables.result ).toInclude( "World" )
    } )

    it( "uses custom greeting when provided", () => {
        var custom = greet( name = "World", greeting = "Hi" )
        expect( custom ).toInclude( "Hi" )
    } )
} )

xUnit-Style Test Example

class {

    function testGreetReturnsString() {
        var result = greet( "World" )
        $assert.isTrue( result.len() > 0 )
    }

    function testGreetIncludesName() {
        var result = greet( "World" )
        $assert.isTrue( result contains "World" )
    }
}

Running Tests

# Run all TestBox tests
box testbox run

# Run a specific spec
box testbox run tests/specs/GreetBIFTest.bx

# Run with a test runner URL
box testbox run "http://localhost:8080/tests"

JUnit Testing (Java Modules)

For Java-heavy modules, use JUnit 5 with standard Gradle test configuration:

@DisplayName( "Greet BIF Tests" )
class GreetTest {

    @Test
    @DisplayName( "Should return greeting with name" )
    void testGreet() {
        var runtime = BoxRuntime.getInstance();
        // Set up test context
        // Invoke BIF
        // Assert results
    }
}

Run JUnit tests:

./gradlew test

Integration Testing

Test your module loaded in a running BoxLang runtime:

class {

    function beforeAll() {
        // Load the module
        variables.moduleService = getBoxRuntime().getModuleService()
        variables.moduleService.loadModule(
            createObject( "java", "java.nio.file.Paths" )
                .get( expandPath( "../../" ) )
        )
    }

    function testModuleIsLoaded() {
        expect( variables.moduleService.hasModule( "myModule" ) ).toBeTrue()
    }

    function testBIFIsRegistered() {
        expect( () => greet( "Test" ) ).notToThrow()
    }
}

CI/CD Integration

GitHub Actions Example

name: Module Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup BoxLang
        uses: ortus-boxlang/setup-boxlang@v1
        with:
          boxlang-version: latest

      - name: Setup Java (for Java modules)
        uses: actions/setup-java@v4
        with:
          java-version: 21

      - name: Build (Java modules)
        run: ./gradlew build

      - name: Run Tests
        run: box testbox run

Test Best Practices

1

Test Module Isolation

Verify your module loads cleanly with no side effects. Test both load and unload cycles.

2

Test Error Handling

Write tests for invalid inputs, missing dependencies, and edge cases.

3

Test With Other Modules

Verify compatibility by testing alongside modules your module depends on or commonly coexists with.

4

Mock External Dependencies

Use MockBox to mock external services in tests:

var mockService = createMock( "models.ExternalService" )
    .$( "call", { status: "ok" } )

Next Steps

• Packaging & Publishing — Build and distribute your module
• Troubleshooting — Common issues and solutions