GitBook: [master] 19 pages modified

Author: lmajano

SUMMARY.md

@@ -282,5 +282,4 @@
   * [Dynamic Testing](architecture-concepts/testing-concepts/dynamic-testing.md)
   * [Developer Focus](architecture-concepts/testing-concepts/developer-focus.md)
   * [Testing Vocabulary](architecture-concepts/testing-concepts/testing-vocabulary.md)
-  * [Testing Tools](architecture-concepts/testing-concepts/testing-tools.md)
 

architecture-concepts/testing-concepts/testing-tools.md

@@ -6,10 +6,10 @@ We have a Github organization called [coldbox-templates](https://github.com/cold
 
 The `coldbox create app` command has integration to our application templates via the `skeleton` argument. This can be the name of each of the templates in our repositories or you can use the following alternatives:
 
-* Name of template in our organization: `advanced,simple,super-simple,etc`
+* Name of template in our organization: `advanced,simple,super-simple,rest, rest-hmvc, vuejs, etc`
 * A name of a ForgeBox entry: `cbtemplate-advanced-script,cbtemplate-simple`
 * A Github shortcut: `github-username/repo`
-* An HTTP/S URL to a zip file containing a template: \`[http://myapptemplates.com/template.zip](http://myapptemplates.com/template.zip)
+* An HTTP/S URL to a zip file containing a template: [http://myapptemplates.com/template.zip](http://myapptemplates.com/template.zip)
 * A folder containing a template: `/opt/shared/templates/my-template`
 * A zip file containing the template: `/opt/shared/templates/my-template.zip`
 

digging-deeper/recipes/application-templates.md

@@ -1,14 +1,18 @@
 # Testing ColdBox Applications
 
-One of the best things you can do when you develop software applications is TEST! I know nobody likes it, but hey, you need to do it right? With the advocation of frameworks today, you get all these great tools to build your software applications, but how do you test your framework code. ColdBox has revolutionized testing MVC and framework code, since you can unit test your event handlers, interceptors, model objects and even do integration testing and test your entire application with no browser at all.
+One of the best things you can do when you develop software applications is TEST! I know nobody likes it, but hey, you need to do it right? With the advocation of frameworks today, you get all these great tools to build your software applications, but how do you test your framework code. ColdBox has revolutionized testing HMVC and framework code, since you can unit test your event handlers, interceptors, model objects and even do **integration testing and true BDD \(Behavior Driven Development\)** and test your entire application with no browser at all.
 
 ColdBox has already all the hooks in place to provide Behavior and Test Driven Development via [TestBox](http://www.ortussolutions.com/products/testbox) and mocking/stubbing capabilities via MockBox.
 
-> TestBox is a testing framework for ColdFusion \(CFML\) that is based on BDD \(Behavior Driven Development\) for providing a clean obvious syntax for writing tests. It also includes MockBox for mocking and stubbing.
+{% hint style="info" %}
+**TestBox** is a testing framework for ColdFusion \(CFML\) that is based on BDD \(Behavior Driven Development\) for providing a clean obvious syntax for writing tests. It also includes MockBox for mocking and stubbing.
+
+**TestBox is included with all ColdBox templates.**
+{% endhint %}
 
 ## Installing TestBox
 
-So let's get started by opening a CommandBox prompt \(`box`\) in your application root and installing TestBox.
+TestBox already comes defined in the `box.json` of all ColdBox application templates.  However, if you have a custom ColdBox app or a custom template, then you can easily install it via CommandBox:
 
 ```bash
 // stable
@@ -18,7 +22,9 @@ install testbox --saveDev
 install testbox@be --saveDev
 ```
 
-> **Info** The `--saveDev` flag tells CommandBox to save TestBox locally only for testing purposes as it will not be used to send TestBox for production \([http://commandbox.ortusbooks.com/content/packages/dependencies.html](http://commandbox.ortusbooks.com/content/packages/dependencies.html)\)
+{% hint style="info" %}
+The --saveDev flag tells CommandBox to save TestBox locally only for testing purposes as it will not be used to send TestBox for production \([http://commandbox.ortusbooks.com/content/packages/dependencies.html](http://commandbox.ortusbooks.com/content/packages/dependencies.html)\)
+{% endhint %}
 
 Please also note that CommandBox ships with tons of commands for interacting with TestBox and ColdBox testing classes. You can explore them by issuing the following commands or viewing the latest CommandBox API Docs \([http://apidocs.ortussolutions.com/commandbox/current](http://apidocs.ortussolutions.com/commandbox/current)\)
 
@@ -32,6 +38,9 @@ testbox create help
 # run tests
 testbox run help
 
+# Watch your files and execute the tests if they change
+testbox watch
+
 # coldbox creation help
 coldbox create help
 ```
@@ -47,11 +56,12 @@ It might be that testing is tedious and takes time to get into the flow of Behav
 * Encourages refactoring to produce testable code
 * Testing is all about behavior and expectations
 
+**Our recommendation is to do BDD and integration testing first.  Unit testing is important but it is more important to verify that your requirements are met.**
+
 ## Resources
 
 * [Wikipedia](http://en.wikipedia.org/wiki/Unit_test) - [http://en.wikipedia.org/wiki/Unit\_test](http://en.wikipedia.org/wiki/Unit_test)
 * [TestBox](http://ortussolutions.com/products/testbox) - [http://ortussolutions.com/products/testbox](http://ortussolutions.com/products/testbox)
-* [TestBox BDD Book](http://testbox.ortusbooks.com) - [http://testbox.ortusbooks.com](http://testbox.ortusbooks.com)
 * [ColdFusion Builder TestBox Extensions](http://forgebox.io/view/coldbox-platform-utilities) - [http://forgebox.io/view/coldbox-platform-utilities](http://forgebox.io/view/coldbox-platform-utilities)
 * [Sublime TestBox Extension](https://github.com/lmajano/cbox-coldbox-sublime) - [https://github.com/lmajano/cbox-coldbox-sublime](https://github.com/lmajano/cbox-coldbox-sublime)
 * [VSCode TestBox Extension](https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-testbox) - [https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-testbox](https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-testbox)

testing/testing-coldbox-applications/README.md

@@ -6,8 +6,8 @@ Before we begin our adventures in testing, let's review what classes does ColdBo
 
 From that super class we have our own ColdBox `BaseTestCase` which is our base class for any testing in ColdBox and the class used for Integration Testing. We then spawn several child classes for targeted testing of different objects in your ColdBox applications:
 
-* `BaseTestCase` - Used for Integration Testing 
-* `BaseModelTest` - Used for model object testing
-* `BaseInterceptorTest` - Used for interceptor testing
-* `BaseHandlerTest` - Used for isolated handler testing
+* `BaseTestCase` - Used for **Integration Testing**
+* `BaseModelTest` - Used for model object unit testing
+* `BaseInterceptorTest` - Used for interceptor unit testing
+* `BaseHandlerTest` - Used for isolated handler unit testing
 

testing/testing-coldbox-applications/coldbox-testing-classes.md

@@ -1,4 +1,61 @@
 # Integration Testing
 
+## Integration Testing
 
+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.
+
+
+
+### Basics
+
+[![](https://github.com/ortus-docs/coldbox-docs/raw/master/full/images/HandlerToTestRelationship.png)](https://github.com/ortus-docs/coldbox-docs/blob/master/full/images/HandlerToTestRelationship.png)
+
+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
+* Most verifications and assertions are done via the contents of the request context object \(request collections\)
+
+```text
+/**
+* My integration test bundle
+*/
+component extends="coldbox.system.testing.BaseTestCase" appMapping="/root"{
+
+    /*********************************** LIFE CYCLE Methods ***********************************/
+
+    function beforeAll(){
+        super.beforeAll();
+        // do your own stuff here
+    }
+
+    function afterAll(){
+        // do your own stuff here
+        super.afterAll();
+    }
+
+/*********************************** BDD SUITES ***********************************/
+
+    function run(){
+
+    }
+```
+
+We will explain later the life-cycle methods and the `run()` method where you will be writing your specs.
+
+> **Hint** Please refer to our BDD primer to start: [http://testbox.ortusbooks.com/content/primers/bdd/index.html](http://testbox.ortusbooks.com/content/primers/bdd/index.html)
+
+### CommandBox Generation
+
+Also remember that you can use CommandBox to generate integration tests with a few simple commands:
+
+```text
+coldbox create integration-test handler=main actions=index,save,run --open
+# help
+coldbox create integration-test help
+```
+
+> **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.
 

testing/testing-coldbox-applications/integration-testing/README.md

@@ -1,4 +1,44 @@
 # Common Methods
 
+The base test cases all inherit from TestBox so here are a few of the common methods you can find in every test bundle CFC \([http://testbox.ortusbooks.com/content/test\_bundles/index.html](http://testbox.ortusbooks.com/content/test_bundles/index.html)\):
 
+```text
+// quick assertion methods
+assert( expression, [message] )
+fail(message)
+
+// bdd methods
+beforeEach( body )
+afterEach( body )
+describe( title, body, labels, asyncAll, skip )
+xdescribe( title, body, labels, asyncAll )
+it( title, body, labels, skip )
+xit( title, body, labels )
+expect( actual )
+
+// extensions
+addMatchers( matchers )
+addAssertions( assertions )
+
+// runners
+runRemote( testSpecs, testSuites, deubg, reporter );
+
+// utility methods
+console( var, top )
+debug( var, deepCopy, label, top )
+clearDebugBuffer()
+getDebugBuffer()
+print( message )
+printLn( message )
+
+// mocking methods
+makePublic( target, method, newName )
+querySim( queryData )
+getmockBox( generationPath )
+createEmptyMock( className, object, callLogging )
+createMock( className, object, clearMethods, callLogging )
+prepareMock( object, callLogging )
+createStub( callLogging, extends, implements )
+getProperty( target, name, scope, defaultValue )
+```
 

testing/testing-coldbox-applications/integration-testing/common-methods.md

@@ -2,3 +2,28 @@
 
 
 
+## 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. The following are the keys created for you in the request collection.
+
+| Key | Description |
+| :--- | :--- |
+| `cbox_handler_results` | The value returned from the event handler method. This key will NOT be created if the handler does not return any data. |
+
+**The handler** \(`main.cfc`\)
+
+```text
+function list(event,rc,prc){
+    return "Hola Luis";
+}
+```
+
+**The spec**
+
+```text
+it( "+homepage renders", function(){
+	var event = execute( event="main.list", renderResults=true );
+	expect(	event.getValue( name="cbox_handler_results" ) ).toBe( "Hola Luis" );
+});
+```
+

testing/testing-coldbox-applications/integration-testing/handler-returning-results.md

@@ -2,3 +2,26 @@
 
 
 
+## HTTP Method Mocking
+
+There are times when building RESTFul web services that you need to mock the incoming HTTP verb. This is done via MockBox:
+
+```text
+function run(){
+
+    describe( "Main Handler", function(){
+    
+      beforeEach(function( currentSpec ){
+        setup();
+      });
+    
+      it( "+homepage renders", function(){
+        prepareMock( getRequestContext() )
+    	    .$( "getHTTPMethod", "DELETE" );
+        FORM.userID = 123;
+        var event = execute( event = "user.delete" );
+      });	
+    });
+}
+```
+

testing/testing-coldbox-applications/integration-testing/http-method-mocking.md

@@ -1,4 +1,36 @@
 # Life-Cycle Events
 
+[![](https://github.com/ortus-docs/coldbox-docs/raw/master/full/images/testing-lifecycle.png)](https://github.com/ortus-docs/coldbox-docs/blob/master/full/images/testing-lifecycle.png)
 
+ColdBox testing leverages TestBox's testing life-cycle events \([http://testbox.ortusbooks.com/content/life-cycle\_methods/index.html](http://testbox.ortusbooks.com/content/life-cycle_methods/index.html)\) in order to prepare the virtual ColdBox application, request context and then destroy it. For performance, a virtual application is loaded for all test cases contained within a test bundle CFC via the `beforeAll()` and destroyed under `afterAll()`.
+
+```text
+function beforeAll(){
+	super.beforeAll();
+	// do your own stuff here
+}
+
+function afterAll(){
+	// do your own stuff here
+	super.afterAll();
+}
+```
+
+> **Important** If you override any of these methods and do not funnel the super call, then you might get cached or unexpected results.
+
+### Improving Performance: Unloading ColdBox
+
+The default for integration testing is that the virtual ColdBox application will be destroyed or unloaded in each test. To keep the virtual application accross requests 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.
+
+```text
+component extends="coldbox.system.testing.BaseTestCase" unloadColdBox=false{
+
+
+	function beforeAll(){
+		this.unloadColdBox = false;
+		super.beforeAll();
+		// do your own stuff here
+	}
+}
+```
 

testing/testing-coldbox-applications/integration-testing/life-cycle-events.md

@@ -2,3 +2,25 @@
 
 
 
+## 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.
+
+```text
+it( "can render users", function(){
+   var event = execute( event="rest.api.users", renderResults=true );
+   expect( event.getValue( "cbox_rendered_content" ) ).toBeJSON();
+} );
+```
+
+### `getRenderedContent()`
+
+In testing mode, the ColdBox request context `event` object has a convenience method called `getRenderedContent()` that will give you the rendered content instead of you going directly to the request context and finding the `cbox_rendered_content` variable.
+
+```text
+it( "can render users", function(){
+   var event = execute( event="rest.api.users", renderResults=true );
+   expect( event.getRenderedContent() ).toBeJSON();
+} );
+```
+

testing/testing-coldbox-applications/integration-testing/rendering-results.md

@@ -1,4 +1,24 @@
 # Test Annotations
 
+Here are the annotations you can add to your testing bundle CFC.
 
+| Annotation | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `appMapping` | string | false | `/` | The application mapping of the ColdBox application to test. By defaults it maps to the root. Extermely important this mapping is a slash notation that points to the root of the ColdBox application to test. |
+| `configMapping` | string | false | `{appMapping}/config/Coldbox.cfc` | 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. |
+| `coldboxAppKey` | string | false | `cbController` | 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. |
+| `loadColdBox` | boolean | false | true | By default the base test case will load the virtual application into the `application`scope so all specs can execute |
+| `unloadColdBox` | boolean | false | true | The base test case will unload the virtual application from the `application` scope after all specs have executed. |
+
+**Examples**
+
+```text
+component extends="coldbox.system.testing.BaseTestCase" appMapping="/apps/MyApp"{}
+
+component extends="coldbox.system.testing.BaseTestCase"
+    appMapping="/apps/MyApp" 
+    configMapping="apps.MyApp.test.resources.Config"{}
+```
+
+> **Caution** The `AppMapping` setting is the most important one. This is how your test connects to a location of a ColdBox application to test.
 

testing/testing-coldbox-applications/integration-testing/test-annotations.md

@@ -1,4 +1,27 @@
 # Test Setup
 
+Here is a spec written for you. Please note that in the `beforeEach()` life-cycle method you need to execute the `setup()` method will will setup a new ColdBox request for each spec you run.
 
+```text
+component extends="coldbox.system.testing.BaseTestCase" appMapping="/apps/MyApp"{
+	
+	function run(){
+
+		describe( "Main Handler", function(){
+
+			beforeEach(function( currentSpec ){
+				// Setup as a new ColdBox request, VERY IMPORTANT. ELSE EVERYTHING LOOKS LIKE THE SAME REQUEST.
+				setup();
+			});
+
+			it( "+homepage renders", function(){
+				var event = execute( event="main.index", renderResults=true );
+				expect(	event.getValue( name="welcomemessage", private=true ) ).toBe( "Welcome to ColdBox!" );
+			});
+		
+		});
+	}
+
+}
+```