Web Support

Mock HTTP exchanges for testing web applications in BoxLang CLI runtime without a web server.

Mock web server for testing BoxLang web applications in CLI runtime. Simulates HTTP requests/responses without needing an actual web server.

📋 Table of Contents

• 📋 Table of Contents

• ⚠️ Warning

• 📦 Installation

• ⚙️ Configuration

• 🚀 Quick Start

• 🔧 BIF Reference

  • mockServerGet()

  • mockRequestNew()

  • mockRequestRun()

• 💡 Examples

  • Basic GET Request

  • POST with JSON

  • Request with Authentication

  • Form Submission

• 🔗 Fluent API

• 🧪 Testing Patterns

  • Test Isolation

  • Multiple Requests

  • Response Inspection

• 📚 Resources

⚠️ Warning

DO NOT install this module into a BoxLang web-runtime! This module is for CLI runtime testing or mocking only and will cause JAR conflicts in web server environments. Not needed for CommandBox or MiniServer.

📦 Installation

# OS Quick Installer
install-bx-module bx-web-support

# CommandBox
box install bx-web-support

⚙️ Configuration

Configure in your ModuleConfig.bx:

settings = {
    port       : 8080,                          // Mock server port
    host       : "localhost",                   // Mock server host
    webRoot    : server.java.executionPath,    // Web root path
    secure     : false,                         // Enable HTTPS
    requestKey : "bxMockServer"                 // Request scope key
};

🚀 Quick Start

// Get mock server
mockServer = mockServerGet()
    .setRequestMethod( "POST" )
    .setRequestPath( "/api/users" )
    .addRequestHeader( "Content-Type", "application/json" )
    .setRequestBody( '{"name": "John"}' );

// Use web-aware BIFs
httpData = getHTTPRequestData();
println( httpData.method ); // POST

🔧 BIF Reference

mockServerGet()

Creates or retrieves cached mock server exchange.

Arguments:

• webroot (string) - Web root path

• host (string) - Server host (default: localhost)

• port (numeric) - Server port (default: 8080)

• secure (boolean) - Enable HTTPS (default: false)

• force (boolean) - Force new instance (default: false)

Returns: MockHTTPExchange

// Get or create server
server = mockServerGet();

// Force new instance
server = mockServerGet( force: true );

// Custom configuration
server = mockServerGet( host: "example.com", port: 9090, secure: true );

mockRequestNew()

Creates mock request builder for fluent configuration.

Arguments:

• method (string) - HTTP method (default: GET)

• path (string) - Request path (default: /)

• body (string) - Request body

• contentType (string) - Content type (default: text/html)

• headers (struct) - Request headers

• urlScope (struct) - URL parameters

• formScope (struct) - Form fields

• cookieScope (struct) - Cookies

• Plus: webroot, host, port, secure

Returns: MockHTTPExchange (builder pattern)

// Builder pattern
mockRequestNew()
    .setRequestMethod( "POST" )
    .setRequestBodyJSON( { name: "John" } )
    .addRequestHeader( "Authorization", "Bearer token" )
    .execute();

// Inline configuration
mockRequestNew(
    method: "PUT",
    path: "/api/users/123",
    body: '{"name": "Jane"}',
    headers: { "Authorization": "Bearer token" }
).execute();

mockRequestRun()

Executes full mock request with all-in-one configuration.

Arguments:

• Request: path, method, pathInfo, queryString, contentType, body, urlScope, formScope, cookieScope, headers

• Response: responseStatus, responseContentType, responseBody, responseHeaders

• Server: webroot, host, port, secure, force

Returns: MockHTTPExchange (executed)

// Simple request
mockRequestRun( path: "/api/users", method: "GET" );

// Complex request
mockRequestRun(
    path: "/api/data",
    method: "POST",
    body: '{"key": "value"}',
    contentType: "application/json",
    headers: { "Authorization": "Bearer token" },
    responseStatus: 201,
    responseBody: '{"success": true}'
);

💡 Examples

Basic GET Request

mockRequestRun( path: "/api/users" );
httpData = getHTTPRequestData();
println( httpData.method ); // GET

POST with JSON

mockRequestNew(
    method: "POST",
    path: "/api/users",
    contentType: "application/json",
    body: '{"name": "John", "email": "[email protected]"}'
).execute();

Request with Authentication

mockServer = mockServerGet()
    .setRequestMethod( "GET" )
    .setRequestPath( "/api/protected" )
    .addRequestHeader( "Authorization", "Bearer xyz789" )
    .addRequestCookie( "sessionId", "sess-123" );

Form Submission

mockRequestRun(
    path: "/contact",
    method: "POST",
    formScope: {
        name: "Jane Doe",
        email: "[email protected]",
        message: "Hello!"
    }
);

🔗 Fluent API

MockHTTPExchange provides fluent methods for request configuration:

Request Configuration:

• setRequestMethod(method) - Set HTTP method

• setRequestPath(path) - Set request path

• setRequestBody(body) - Set request body

• setRequestBodyJSON(struct) - Set JSON body (auto content-type)

• setRequestBodyXML(string) - Set XML body (auto content-type)

• setRequestContentType(type) - Set content type

Headers & Parameters:

• addRequestHeader(name, value) - Add single header

• addRequestHeaders(struct) - Add multiple headers

• addURLParam(name, value) - Add URL parameter

• addURLParams(struct) - Add multiple URL parameters

• addFormField(name, value) - Add form field

• addFormFields(struct) - Add multiple form fields

• addRequestCookie(name, value) - Add cookie

Execution & Inspection:

• execute() - Execute the request

• getResponseBody() - Get response body

• getResponseStatus() - Get status code

• getMockRequestHeaders() - Get request headers

• getMockResponseHeaders() - Get response headers

• getMockForm() - Get form scope

• getMockURL() - Get URL scope

Test Utilities:

• clearRequestData() - Reset request data

• clearResponseData() - Reset response data

• clearAll() - Reset everything

🧪 Testing Patterns

Test Isolation

// Reset between tests
mockServer = mockServerGet();
mockServer.clearAll();

// Or force new instance
mockServer = mockServerGet( force: true );

Multiple Requests

// Test different methods
mockRequestNew( method: "GET", path: "/api/users" ).execute();
mockRequestNew( method: "POST", path: "/api/users", body: "{}" ).execute();
mockRequestNew( method: "DELETE", path: "/api/users/123" ).execute();

Response Inspection

mockServer = mockRequestRun(
    path: "/api/test",
    method: "POST",
    body: '{"test": true}'
);

// Inspect
status = mockServer.getResponseStatus();
body = mockServer.getResponseBody();
headers = mockServer.getMockResponseHeaders();

📚 Resources

• GitHub Repository

• Issue Tracker

• BoxLang Documentation