Skip to content

API

Jump to bottom
titulus edited this page Aug 6, 2013 · 51 revisions

##Contents

##Basic properties Basic API availible through test object ###Methods:

  • test.done() - outputs the result to the console.

    This method must be a last line of code in your tests.

    example:

    var a = 1;
var b = 2;
test.it(a+b === 3);

test.done(); // outputs result

    test.done()

####tests Tests is basic functional of test.it framework.

They all:

  • check some received value or values;
  • can receive exact number of arguments (return an error instead of the value if not);
  • add their result in the current level stack.
  • can be passed, failed and ended with error

In output every test looks like: tests status: comment description/error arguments array

where
`status` - display result of test (`passed`, `failed` or `error`)

There are list of all availible tests (v.1.0.0):

  • test.it( value ) - checks value for non-false value.

    Simplify it looks like: javascript if ( value ) {return 'pass'} else {return 'fail'} So every value which will pass if test - will pass test.it( value ). ```javascript // Next tests will pass test.it( 1 ); test.it( 'text' ); test.it( true ); test.it( window ); test.it( alert ); test.it( 2+2 === 4 ); var a = 10; test.it( a > 5 );

// Next tests will fail test.it( 0 ); test.it( '' ); test.it( false ); test.it( 2+2 === 5 ); var a = 3; test.it( a > 5 ); test.it( null ); test.it( NaN );

// Next line will return error test.it( ); test.it( 1, 2, 3 );

// Next line will throw the ReferenceError and will not be executed test.it( myNotDefinedVariable ); test.it( myNotDefinedFunction() ); ```

  • test.it( value1, value2 ) - checks the equality between value1 & value2.

    There are not simply value1 == value2. But used deepCompare() function from here. It can compare any type of values, but obviously they must be of the same type.

    

    • 



// Next tests will pass
test.it( 5, 5 )
test.it( 'text', 'text' )
test.it( [1,2,3], [1,2,3] )
test.it( {a:1,b:2}, {a:1,b:2} )


// Next tests will fail
test.it( 5, 1 )
test.it( 'text', 'line' )
test.it( '10', 10 )
test.it( [1,2,3], [3,2,1] )
test.it( {a:1,b:2}, {a:1,b:2,c:3} )
```


    

  • 

     test.them( values ) - checks for non-false all values in an values.
    

    Is similar to test.it( value ) but check for non-false more then 1 values, but they must be contained in values array.
    

    

    • 



// Next tests will pass
test.them( [1,'text',true,window,alert] )


// Next tests will fail
test.them( [1,'text',true,window,alert,false] )


// Next line will return error
test.them( )
test.them( 1 )
test.them( 1, 2 )
test.them( [1,2], 2 )
```


    

  • 

     test.type( value, type ) - checks the type (function, object, ...) of an value.
    

    Uses test.typeof() function - more powerful then common typeof(). It recognizes array, boolean, date, error (evalerror, rangeerror, referenceerror, syntaxerror, typeerror, urierror), function, nan & number, object, regexp, string, window, dom, nodelist.
    

    There no matter case of type name. Feel free to use 'String' or 'string' or 'StRiNg' etc.
    

    

    • 



// Next tests will pass
test.type( 1, 'number' )
test.type( 'text', 'String' )
test.type( alert, 'function' )


// Next tests will pass
test.type( 'text', 'number' )
test.type( alert, 'String' )
test.type( 1, 'function' )


// Next line will return error
test.type( )
test.type( 1 )
test.type( 1, 2 )
test.type( 1, 'myType' )
test.type( 1, 'number', 3 )
```


    

  • 

     test.types( values [, type] ) - checks the equality between types of all values in values. If type defined - types of values will be compared with it.
    

    Is similar to test.type( value, type ) but check types more then 1 values, but they must be contained in values array.
    

    

    • 



// Next tests will pass
test.types( [1,2,3,new Number()] )
test.types( [1,2], 'number' )
test.types( ['asd','dsa'], 'string' )


// Next tests will fail
test.types( [1,2,'text'] )
test.types( ['asd','dsa'], 'number' )


// Next line will return error
test.types( )
test.types( 1 )
test.types( 1, 2 )
test.types( 1, 'number' )
test.types( [1,2], 'myType' )
test.types( [1,2], 'number', 3 )
```
###groups
Groups are extrimly useful tool, which allows multi-level combining tests.


    

  • 

     test.group( name, function(){ ... } ) - made new group.
    

    If group already exist, extend it.
    

    

    • 



// will make group 'first group'
test.group('first group',function(){
// ... here goes first tests
});


// add tests to group 'first group'
test.group('first group',function(){
// ... here goes second tests
});
Code above is similar to:javascript
// will make group 'first group'
test.group('first group',function(){
// ... here goes first tests
// ... here goes second tests
});
```


    

  • 

     test.group( name ) - return test object - to provide nesting and chaining
    

    Provide transit to next-level group
    

    

    • 



// will make group
test.group('first group',function(){
// ... here goes first tests
});


// return link to group 'group in first group'
test.group('first group')
####Nesting `test.group` provide multi-level nesting. `test.group( name, function(){ ... } )` can be nested in another `test.group( name, function(){ ... } )` like this:javascript
// will make group with group in it
test.group('first group',function(){
// ... here goes first tests
test.group('group in first group',function(){
// ... here goes second tests
});
// ... here goes third tests
});
With `test.group( name )` you can use nesting this wayjavascript
// will make group with group in it
test.group('first group',function(){
// ... here goes first tests
test.group('group in first group',function(){
// ... here goes second tests
});
// ... here goes third tests
});


// add tests to group 'group in first group'
test.group('first group').group('group in first group',function(){
// ... here goes fourth tests
});
Code above is similar to: javascript
// will make group with group in it
test.group('first group',function(){
// ... here goes first tests
test.group('group in first group',function(){
// ... here goes second tests
// ... here goes fourth tests
});
// ... here goes third tests
});
```


Groups throw error if recieved 0 or more then 2 arguments, or if there are 1 arguments, with non existing name:
```javascript
test.group( );
test.group('wrong group',function(){
    test.it(true); 
},3);
test.group('non existing group')
```



###Attributes:


    

  • 

     test.root - return zero-level group.
    

    All result will get in it. Any type of output bases on it.
    

    Empty root has structure:
    

    

    • 



{
type: "group",
name: "root",
status: undefined,
time: 0,
result: {
pass: 0,
fail: 0,
error: 0,
total: 0
},
stack: []
}
```
Every test located outside groups and first-level groups will get into root.stack.


When any test/group get into any stack, `result` counters and `status` of current and all previous levels (till `root`) are updates. But counters of `result` mean number of test/groups in current level only.



##Chaining
Chain - set of functions, starts from Chain-opener, continue by Chain-links (there is no limit on the number) and ended with Chain-closer.


chainOpener().chainLink().chainLink().chainCloser();
// or
chainOpener()
  .chainLink()
  .chainLink()
  .chainCloser();


###Chain-openers



###Chain-links


    

  • 

     .comment( text ) - add comment to test/group
    

    If there are more then one .comment( text ) in chain - only last will be used.
    

    

    • 



test.group('first group',function(){
test.it(true).comment('test with true argument');
}).comment('group with only one test');
```


    

  • 

     .callback( function(){ /* funcIfpass */}[, function(){ /* funcIffail */}[, function(){ /* funcIferror */}]]) - will execute funcIfpass if test/group pass, funcIffail if it failed, funcIferror if it cause error.
    

    funcIffail and funcIferror are not required.
    

    

    • 



// will cause two alerts: 'test pass' - first, and 'group pass' - after
test.group('first group',function(){
test.it(true).callback(function(){alert('test pass')}
,function(){alert('test fail')}
,function(){alert('test error')});
}).callback(function(){alert('group pass')}
,function(){alert('group fail')}
,function(){alert('group error')});
```


###Chain-closers
They all return something. So it makes sense to assign chain with closer to some variable, or use it like argument in some function.


    

  • 

     .result() - return result of test/group
    

    Returned value has boolean type.
    

      

    • 
true - if test had pass
      • 

    • 
false - otherwise
      • 

    

    

    • 



// will cause two alerts: 'test true' - first, and 'group true' - after
alert('group '+test.group('first group',function(){
alert('test '+test.it(true).result());
}).result());
```


    

  • 

     .arguments() - return single argument or array of arguments from test (not from group!)
    

    This is only Chain-closer that can't be used in chains started from test.group, because groups are not saves their arguments in arguments array.
    

    

    • 



// will cause alert: 'test true'
alert('test '+test.it(true).arguments());


// even if test cause error, there will be allert: 'test 1,2,3'
alert('test '+test.it(1,2,3).arguments());
```


So you can use chains like this:


test.group('first group',function(){test.it('single')})
    .comment('group with simple test')
    .callback(function(){alert('test has been passed')})
    .result() // -> true
test.group('second group',function(){test.it('first','second')})
    .comment('group with test equalence')
    .result() // -> false

test.it('single')
    .comment('test a simple string')
    .arguments() // -> 'single'
test.it('first','second')
    .comment('test two string')
    .callback(null, function(){alert('test has been failed')})
    .arguments() // -> ['first','second']


##features
They are not produce any tests or tests manipulations. There are some usefull fuctions, which are used in core of test.it framework.


    

  • 

     test.typeof( value ) - determines and return the type of value.
    

    It recognizes array, boolean, date, error (evalerror, rangeerror, referenceerror, syntaxerror, typeerror, urierror), function, nan & number, object, regexp, string, window, dom, nodelist.
    

    

    • 



test.typeof(1); // -> Number
test.typeof(NaN); // -> NaN
test.typeof(Infinity); // -> Number
test.typeof('text'); // -> String
test.typeof(window); // -> Window
test.typeof(null); // -> null
test.typeof(document); // -> HTML
```


    

  • 

     test.trace() - return list (joined by "\n") of lines in your code that have been performed to call the current line.
    

    It is not true trace() because result are filtered from any lines in core of test.it framework
    

    

    • 



(function firstFunction(){
(function secondFunction(){
console.log(test.trace());
})()
})()
Code above will put in console *Chrome*:
secondFunction (http://path/to/script.js:3:26)
firstFunction (http://path/to/script.js:4:7)
http://path/to/script.js:5:3
```


              


          



  
          

            


            
Clone this wiki locally