Commits

Anonymous committed f9ad631

add robodoc comments

Comments (0)

Files changed (1)

 if(typeof fox === "undefined" || !fox) fox={};
+
+/****h* fox.test/fox.test
+* DESCRIPTION
+*       A simple light-weight framework for writing JavaScript
+* test pages.
+*
+* NOTES
+*       framework is not cross-browser compatible
+*
+* SEE ALSO
+*       https://bitbucket.org/bworkman/js-test
+*
+* COPYRIGHT
+* The MIT License (MIT)
+* 
+* Copyright (c) 2013 Bradley Workman
+* 
+* Permission is hereby granted, free of charge, to any person obtaining a copy
+* of this software and associated documentation files (the "Software"), to deal
+* in the Software without restriction, including without limitation the rights
+* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+* copies of the Software, and to permit persons to whom the Software is
+* furnished to do so, subject to the following conditions:
+*
+* The above copyright notice and this permission notice shall be included in
+* all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+* THE SOFTWARE.
+******
+*     There are probably more comprehensive test frameworks available, but
+* I wrote this one myself for practice and experience. For production 
+* environment testing or commercial grade, I recommend researching a more
+* rigorous framework.
+*/
 (function(){
 	if(fox.test) return;
 
+        /****f* fox.test/print
+        * DESCRIPTION
+        *       private -- used to write messages html page
+        *
+        * PARAMETERS
+        *       (string) msg -- message to print
+        *
+        * SIDE EFFECTS
+        *       see document.write
+        *
+        * RESULT
+        *       none
+        *
+        * TODO
+        *       - add support for arbitrary input objects
+        *       - add support for pretty-printing
+        *
+        * SOURCE
+        */
         function print(msg)
         {
         	msg = msg.replace(/\t/gi, '<span style="display:inline-block;width: 32px;"></span>');
                 msg = msg.replace(/\n/gi, '<br>');
                 document.write(msg);
         }
+        /*******/
 
+        /****f* fox.test/println
+        * DESCRIPTION
+        *       private -- appends a linebreak to msg and then calls print
+        *
+        * PARAMETERS
+        *       (string) msg -- message to print
+        *
+        * SIDE EFFECTS
+        *       see print
+        *
+        * RESULT
+        *       none
+        *
+        * SOURCE
+        */
         function println(msg)
         {
                 print(msg + "\n");
         }
+        /*******/
 
         fox.test = {
+                /****f* fox.test/getStack
+                * DESCRIPTION
+                *       public -- returns the stack in a more structured form
+                *
+                * PARAMETERS
+                *       none
+                *
+                * SIDE EFFECTS
+                *       none
+                *
+                * RESULT
+                *       returns stack in the following form:
+                * [
+                *   [function, line, column],
+                *   ...
+                * ]
+                *
+                * TODO
+                *       - expand browser compatibility
+                *
+                * SOURCE
+                */
                 getStack:function(){
                         var stack = (new Error()).stack.split("\n");
 
                         stack.splice(0,1);
                         return stack;
                 },
+                /*******/
+                
+                /****f* fox.test/assert
+                * DESCRIPTION
+                *       public -- performs an equivelance test
+                * and throws an error if the relation fails.
+                *
+                * PARAMETERS
+                *       (obj) a          -- if 'b' and 'strict' are  undefined, assert tests that 
+                * 'a' === 'true', else 'a' will be compared to 'b'
+                *
+                *       (obj) b          -- object to compare to 'a'
+                *
+                *       (boolean) strict -- if 'strict' === 'true', 'a' and 'b' will be compared
+                * using the '===' relation
+                *
+                * SIDE EFFECTS
+                *       if assert fails, an error is thrown
+                *
+                * RESULT
+                *       always returns 'true'
+                *
+                * SOURCE
+                */
                 assert:function(a,b,strict){
 
                         if(typeof b === "undefined")
                                         assertion:a + r + b
                                 }));
                         }
+
+                        true;
                 },
+                /*******/
+
+                /****f* fox.test/run
+                * DESCRIPTION
+                *       public -- runs a set of test functions with
+                * a given scope, prints the results and (possibly) debug
+                * information to the current html document.
+                *
+                * PARAMETERS
+                *       (obj) suite       -- expected to be an object with the following
+                * signature:
+                *       {
+                *               __TITLE__:(string),
+                *               __DOC__:(string),
+                *               _init: (function),
+                *               test1: (function),
+                *               test2: (function),
+                *               ...
+                *       }
+                *
+                *       (boolean) verbose -- if 'true', debug information is printed
+                *
+                * SIDE EFFECTS
+                *       see println, print
+                *
+                * RESULT
+                *       always returns 'true'
+                *
+                * NOTES
+                *       - test functions must be numbered [1,n] continuous
+                *       - result of '_init' will be used as scope for the
+                * calls of 'text<x>'
+                *       - _init can be a variable
+                *       - scope must not break 'JSON.stringify'
+                *
+                * TODO
+                *       - support non-continuous numbering of test functions
+                *       - print more structured results
+                *
+                * SOURCE
+                */
                 run:function(suite, verbose){
-                        println("<strong>"+suite.__TITLE__+"</strong>");
-                        println("<em>"+suite.__DOC__+"</em>");
 
-                        var scope = suite._init();
+                        var tmp = "&lt;anonymous suite&gt;";
+                        if(typeof suite.__TITLE__ !== "undefined")
+                                tmp = suite.__TITLE__;
+                        println("<strong>"+tmp+"</strong>");
+
+                        tmp = "functionality is unknown";
+                        if(typeof suite.__DOC__ !== "undefined")
+                                tmp = suite.__DOC__;
+                        println("<em>"+tmp+"</em>");
+
+                        var scope = {};
+                        if(typeof suite['_init'] !== "undefined")
+                                scope = suite._init();
+
                         var i=1;
                         while(typeof suite["test"+i] === "function")
                         {
                                 i++;
                         }
                 }
+                /*******/
         };
 
 })();