Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The BaseTestCase
leverages an internal virtual ColdBox application so you can do integration testing. Meaning that whenever you extend from the BaseTestCase
the virtual ColdBox will be loaded. However, you can tell the testing framework to NOT load it by using the this.loadColdBox
variable:
This is a great approach if you still want to leverage the base test case for unit testing but without loading the entire virtual application.
ColdBox testing leverages TestBox's testing life-cycle events (https://testbox.ortusbooks.com/primers/testbox-bdd-primer/life-cycle-methods) in order to prepare the virtual ColdBox application, request context and then destroy it. By default, a virtual application is loaded for all test cases contained within a test bundle CFC via the beforeAll()
and destroyed under afterAll()
.
Important If you override any of these methods and do not funnel the super call, then you might get cached or unexpected results.
The default for integration testing is that the virtual ColdBox application will be destroyed or unloaded in each test. To keep the virtual application running across multiple test bundle tests you will need to use the unloadColdBox=false
annotation or the this.unloadColdBox=false
setting in your beforeAll()
method. This will stop the testing classes from destroying ColdBox and improving performance.
If you are building RESTFul services or you want to be able to simulate requests with other HTTP verbs that are not GET, then we have created a set of methods so you can test ANY HTTP method, param and even request headers.
The request()
method is the method to use to simulate ANY HTTP verb operation and get a response rendered into the request context. Please note that it expects a route
and not an event. This means that it will also test your URL mappings, so make sure you pass the right URL.
Since we are simulating a browser, the testing framework needs to know when to prepare a new virtual request internally. This is achieved via the setup()
method provided to us via the BaseTestCase
object. This method internally will simulate a new virtual request, if NOT, every test case will be treated as if you are in the same request.
The best way to accomplish this is to leverage the beforeEach()
life-cycle event method. This makes sure that each spec execution is a new virtual request.
Here are the annotations you can add to your testing bundle CFC to change behavior:
Examples
Caution The
AppMapping
setting is the most important one. This is how your test connects to a location of a ColdBox application to test.
We will begin our adventure with integration testing. Integration testing allows you to test a real life request to your application without using a browser. Your test bundle CFC will load a new virtual application for you to test each specification under it; all aspects of your application are loaded: caching, dependency injection, AOP, etc. Then you can target an event to test and verify its behavior accordingly. First of all, these type of tests go in your integration
folder of your test harness or in the specific module folder if you are testing modules.
Here are the basics to follow for integration testing:
Create one test bundle CFC for each event handler you would like to test or base it off your BDD requirements
Bundle CFC inherits from coldbox.system.testing.BaseTestCase
The bundle CFC can have some annotations that tell the testing framework to what ColdBox application to connect to and test
Execution of the event is done via the execute()
method, which returns a request context object
Execution of API requests can be done via the convenience request()
method or the HTTP method aliases: get(), post(), put(), patch(), head(), options()
Most verifications and assertions are done via the contents of the request context object (request collections)
We will explain later the life-cycle methods and the run()
method where you will be writing your specs.
Also remember that you can use CommandBox to generate integration tests with a few simple commands:
Info Please also note that whenever you create a handler, interceptor or model with CommandBox it will automatically create the integration or unit test for you.
The execute()
method is your way of making requests in to your ColdBox application. It can take the following parameters:
Name | Type | Default | Description |
---|
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.
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.
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.
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
)
The spec
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
)
The spec
If you are expecting status codes to do expectations against, you can use our two convenience methods:
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.
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:
The possible arguments are:
event
URL
URI
queryString
persist
persistStruct
addToken
ssl
baseURL
postProcessExempt
statusCode
Hint Please refer to our BDD primer to start:
Method | Description |
---|
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.
| Get the status code for a ColdBox integration test |
| Get the status code set in the CFML engine. |
Annotation | Type | Required | Default | Description |
| string | false |
| The application mapping of the ColdBox application to test. By defaults it maps to the root. Extremely important this mapping is a slash notation that points to the root of the ColdBox application to test. |
| string | false |
| The configuration file to load for this test, which by convention uses the same configuration as the application uses. This is a dot notation path to a configuration CFC. |
| string | false |
| The named key of the ColdBox controller that will be placed in application scope for you to simulate the ColdBox application. Used mostly on advanced testing cases where you have altered the default application key. |
| boolean | false | true | By default the base test case will load the virtual application into the |
| boolean | false | true | The base test case will unload the virtual application from the |
| string | --- | The event to execute (e.g. 'main.index') |
| string | --- | The route to execute (e.g. '/login' which may route to 'sessions.new') |
| string | --- | The query string to use in the request |
| boolean |
| If |
| boolean |
| If |
| struct |
| A collection of arguments to passthrough to the calling event handler method. |
| struct |
| If true, then it will try to do the normal rendering procedures and store the rendered content in the RC as |
| boolean |
| If true, then ColdBox will process any errors through the exception handling framework instead of just throwing the error. |
| string |
| The domain or subdomain that you would like to simulate the request with. |