ColdBox HMVC Documentation
DocsSourceSupportTraining
7.x
7.x
  • Introduction
    • Contributing Guide
    • Release History
      • What's New With 7.4.0
      • What's New With 7.3.x
      • What's New With 7.2.0
      • What's New With 7.1.0
      • What's New With 7.0.0
        • Release Notes
    • Upgrading to ColdBox 7
    • What is ColdBox
    • What is MVC
    • About This Book
      • Author
  • For Newbies
    • 60 Minute Quick Start
      • Installing ColdBox
      • My First ColdBox Application
      • My First Handler & View
      • Linking Events Together
      • Working with Events
      • Adding A Layout
      • Adding A Model
      • RESTFul Data
      • Next Steps
    • Getting Started Guide
  • Getting Started
    • Installation
    • Application Templates
    • Conventions
    • Configuration
      • ColdBox.cfc
        • Configuration Directives
          • CacheBox
          • ColdBox
          • Conventions
          • Environments
          • Flash
          • InterceptorSettings
          • Interceptors
          • Layouts
          • LayoutSettings
          • LogBox
          • Modules
          • ModuleSettings
          • Settings
          • WireBox
        • System Settings (Java Properties and Environment Variables)
      • Using Settings
      • Bootstrapper - Application.cfc
  • The Basics
    • Request Context
    • Routing
      • Requirements
        • Rewrite Rules
      • Application Router
      • Routing DSL
        • Routing By Convention
        • Pattern Placeholders
        • Routing Methods
        • Resourceful Routes
        • Named Routes
        • Routing Groups
        • Routing Namespaces
      • Building Routable Links
      • RESTFul Extension Detection
      • HTTP Method Spoofing
      • HTML Base Tag
      • Pathinfo Providers
    • Event Handlers
      • How are events called?
      • Getting & Setting Values
      • Setting Views
      • Relocating
      • Rendering Data
      • Sending Files
      • Interception Methods
        • Pre Advices
        • Post Advices
        • Around Advices
      • Model Integration
        • Model Data Binding
      • HTTP Method Security
      • Implicit Methods
      • Executing Events
      • Executing Routes
      • Viewlets - Reusable Events
      • Event Caching
      • Validation
    • Layouts & Views
      • Views
        • Rendering Views
        • Rendering External Views
        • Rendering With Local Variables
        • Rendering Collections
        • View Caching
        • View Helpers
        • View Events
      • Layouts
        • Basic Layouts
        • Default Layout
        • Nested Layouts
        • Overriding Layouts
        • Layouts From A Module
        • Layout Helpers
        • Layout Events
      • Implicit Layout-View Declarations
      • Helpers UDF's
      • ColdBox Elixir
    • Models
      • Domain Modeling
        • Service Layer
        • Data Layers
        • Book
      • Conventions Location
      • WireBox Binder
      • Super Type Usage Methods
      • Injection DSL
        • ColdBox Namespace
        • CacheBox Namespace
        • EntityService Namespace
        • Executor Namespace
        • Java Namespace
        • LogBox Namespace
        • Models Namespace
        • Provider Namespace
        • WireBox Namespace
      • Object Scopes
      • Coding: Solo Style
        • Datasource
        • Contact.cfc
        • ContactDAO.cfc
        • ContactService.cfc
        • Contacts Handler
      • Coding: ActiveEntity Style
        • ORM
        • Contact.cfc
        • Contacts Handler
        • Views
      • Coding: Virtual Service Layer
        • ORM
        • Contacts.cfc
        • Contacts Handler
        • Views
      • Coding: ORM Scaffolding
        • ORM
        • Contacts.cfc
        • Scaffold
    • Interceptors
      • How do they work?
        • Conventions
      • Interceptor Declaration
      • Interceptor Registration
      • Dynamic Registration
      • Core Interception Points
        • Application Life Cycle Events
        • Object Creating Events
        • Layout-View Events
        • Module Events
        • CacheBox Events
      • Restricting Execution
      • Interceptor Output Buffer
      • Custom Events
        • Configuration Registration
        • Programmatic Registration
        • Listening
        • Announcing Interceptions
      • Unregistering Interceptors
      • Reporting Methods
      • Interceptor Asynchronicity
        • Async Announcements
        • Async Listeners With Join
        • Async Listeners No Join
        • Asynchronous Annotations
  • HMVC
    • Modules
      • Core Modules
      • Locations
      • Parent Configuration
      • Module Layout
        • Changing The Module Layout
      • Module Service
        • Module Lifecycle
        • Module Registration
        • Module Activation
        • Module Unloading
        • Common Methods
        • Loading New Modules
        • Loading A-la-carte Modules
        • Module Events
      • ModuleConfig
        • Public Module Properties
        • The Decorated Variables
        • The configure() Method
        • Module Settings
        • Environment Control
        • Interceptor Events
      • Module Event Executions
      • URL Routing
        • Default Route Execution
        • Module Routes Files
      • Module Async Scheduling
      • Request Context Module Methods
      • Layout and View Renderings
        • Layout/View Discovery
        • Overriding Views
        • Overriding Layouts
        • Default Module Layout
        • Explicit Module Renderings
      • Models
      • Module CF Mappings
      • Module Dependencies
      • Module Helpers
      • Module Bundles
      • Module Inception
  • Testing
    • Testing Quick Start
    • Testing ColdBox Applications
      • Test Harness
      • ColdBox Testing Classes
      • Testing Methods
      • Integration Testing
        • Test Annotations
        • Life-Cycle Events
        • Request Setup()
        • The execute() Method
        • HTTP Testing Methods
        • Testing Without Virtual Application
      • Interceptor Testing
      • Model Object Testing
      • Tips & Tricks
  • Digging Deeper
    • Async Programming
      • Async Pipelines & Futures
      • Parallel Computations
      • Executors
      • Scheduled Tasks
    • ColdBox Proxy
      • Getting Started
      • The Base Proxy Object
      • The Event Handlers
        • Distinguishing Request Types
        • RenderData()
      • Proxy Events
      • Standard Return Types
      • Caveats & Gotchas
    • Controller Decorator
    • ColdBox Scheduled Tasks
    • Flash RAM
      • Flash Storage
      • Using Flash RAM
      • Creating Your Own Flash Scope
    • HTML Helper
    • REST Handler
    • Request Context Decorator
    • Recipes
      • Building REST APIs
      • ColdBox Exception Handling
      • Debugging ColdBox Apps
      • Clearing the View Cache
      • Basic HTTP Authentication Interceptor
  • Architecture Concepts
    • How ColdBox Works
Powered by GitBook
On this page
  • Rendering Results
  • Handler Returning Results
  • Rendering Data
  • Getting The Status Code
  • Mocking Relocations
  • Subdomain/Domain Routing

Was this helpful?

Edit on GitHub
Export as PDF
  1. Testing
  2. Testing ColdBox Applications
  3. Integration Testing

The execute() Method

Last updated 2 years ago

Was this helpful?

The execute() method is your way of making requests in to your ColdBox application. It can take the following parameters:

Name
Type
Default
Description

event

string

---

The event to execute (e.g. 'main.index')

route

string

---

The route to execute (e.g. '/login' which may route to 'sessions.new')

queryString

string

---

The query string to use in the request

private

boolean

false

If true, sets the event execution as private.

prePostExempt

boolean

false

If true, skips the pre- and post- interceptors. e.g., preEvent, postHandler, etc.

eventArguments

struct

{}

A collection of arguments to passthrough to the calling event handler method.

renderResults

struct

false

If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as cbox_rendered_content.

withExceptionHandling

boolean

false

If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error.

domain

string

cgi.server_name

The domain or subdomain that you would like to simulate the request with.

This method will execute any ColdBox event/route just like if it's coming from the browser or mobile app. You will get back a request context object from which you can then do assertions with it.

it( "can render some restful data", function() {
    var event = execute( "main.data" );

    debug( event.getHandlerResults() );
    expect( event.getRenderedContent() ).toBeJSON();
} );

WARNING: Please note that this method is limited to simulating GET operations. If you are building RESTFul services, then you will need to use our discussed next.

Rendering Results

The execute() method has an argument called renderResults which defaults to false. If you pass in true then ColdBox will go through the normal rendering procedures and save the results in a request collection variable called: cbox_rendered_content and expose to you a method in the request context called getRenderedContent(). It will even work with renderData() or if you are returning RESTful information.

Then you can easily assert what the content would have been for an event.

it( "can render users", function(){

   var event = execute( event="rest.api.users", renderResults=true );
   
   // From Value
   expect( event.getValue( "cbox_rendered_content" ) ).toBeJSON();
   // From Method
   expect( event.getRenderedContent() ).toBeJSON();
   
} );

Handler Returning Results

If you have written event handlers that actually return data, then you will have to get the values from the request collection to assert them. ColdBox will create a variable called: cbox_handler_results and expose to you a method in the request context called getHandlerResults() so you can do your assertions.

The handler (main.cfc)

function list( event, rc, prc ){
    return "Hola Luis";
}

The spec

it( "+homepage renders", function(){
    var event = execute( event="main.list", renderResults=true );
    
    // From value
    expect(	event.getValue( "cbox_handler_results" ) ).toBe( "Hola Luis" );
    // From Method
    expect( event.getHandlerResults() ).toBe( "Hola Luis" );
});

Rendering Data

If you use the renderData() method in your handler, you can also get that rendering data struct via our convenience method: getRenderData() or via the request collection private variable: cbox_renderdata.

The handler (main.cfc)

function data( event, rc, prc ){
    event.renderData( data=myService.getData(), type="json" );
}

The spec

it( "can render data", function(){
    var event = execute( event="main.data", renderResults=true );
    
    // From value
    expect(	event.getPrivateValue( "cbox_renderdata" ).type ).toBe( "json" );
    // From Method
    expect( event.getRenderData().type ).toBe( "json" );
});

Getting The Status Code

If you are expecting status codes to do expectations against, you can use our two convenience methods:

Method
Description

getStatusCode()

Get the status code for a ColdBox integration test

getNativeStatusCode()

Get the status code set in the CFML engine.

You most likely will use the getStatusCode() as this is the one used in mocks and relocations, the other one is a RAW approach to get the underlying status code from the page context response.

Mocking Relocations

ColdBox will wire itself up with some mocking classes to intercept those relocations for you and place those values in the request collection for you so you can assert them. It creates a key called relocate in the request collection and any arguments passed to the method are also saved as keys with the following pattern:

relocate_{argumentName}

The possible arguments are:

  • event

  • URL

  • URI

  • queryString

  • persist

  • persistStruct

  • addToken

  • ssl

  • baseURL

  • postProcessExempt

  • statusCode

it( "can do a relocation", function() {
    var event = execute( event = "main.doSomething" );
    expect( event.getValue( "relocate_event", "" ) ).toBe( "main.index" );
} );

Subdomain/Domain Routing

describe( "subdomain routing", function(){
	beforeEach( function(){
		setup();
	} );
	
	it( "can match on a specific domain", function(){
		var event = execute( route: "/", domain: "subdomain-routing.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.index" );
	} );
	
	it( "skips if the domain is not matched", function(){
		var event = execute( route: "/", domain: "not-the-correct-domain.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "main.index" );
	} );
	
	it( "can match on a domain with wildcards", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.show" );
	} );
	
	it( "provides any matched values in the domain in the rc", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "username" );
		expect( rc.username ).toBe( "luis" );
	} );
} );

If you are building multi-tenant applications with ColdBox and are leveraging , then you can easily use the domain argument to simulate the domain in play for THAT specific spec execution.

HTTP Testing Methods
domain and subdomain routing