##Overview
This project meets a need for lightweight standalone cross platform Javascript assert and logging tools. Both of these techniques can be used to reduce the necessity for a debugger and hence saving time in developing applications (e.g., typically routinely checking the validity of arguments passed to functions).
The functions themselves have been ported across from Yahoo's YUI framework
with as few changes to the original code as has been possible
(all modifications are documented in square brackets and flagged with a #yp
tag).
Note when using these functions:
- the results of passing non-valid arguments are undefined
- the project is currently at release candidate status -- while all functions have received some testing, this was by no means a comprehensive testing of every fork in the code, bugs conceivably could have been introduced during the porting process (YUI code has also been known to have the occassional albeit extremely rare bug)
##Currently Available Libraries and Functions
###Assert functions
YUIAssert.js (ported from YUI Assert.js, AssertionError.js, ComparisonFailure.js, UnexpectedValue.js)
Equality:
Boolean:
Special value:
- YUIAssert.isNaN
- YUIAssert.isNotNaN
- YUIAssert.isNull
- YUIAssert.isNotNull
- YUIAssert.isUndefined
- YUIAssert.isNotUndefined
Instance:
- YUIAssert.isArray
- YUIAssert.isBoolean
- YUIAssert.isFunction
- YUIAssert.isInstanceOf
- YUIAssert.isNumber
- YUIAssert.isObject
- YUIAssert.isString
- YUIAssert.isTypeOf
Error:
YUIAssertX.js (requires YUIAssert.js, YUILang.js)
YUIArrayAssert.js (requires YUIAssert.js, ported from YUI ArrayAssert.js)
- YUIArrayAssert.contains
- YUIArrayAssert.doesNotContain
- YUIArrayAssert.containsItems
- YUIArrayAssert.doesNotContainItems
- YUIArrayAssert.containsMatch
- YUIArrayAssert.doesNotContainMatch
- YUIArrayAssert.indexOf
- YUIArrayAssert.lastIndexOf
- YUIArrayAssert.itemsAreEqual
- YUIArrayAssert.itemsAreSame
- YUIArrayAssert.itemsAreEquivalent
- YUIArrayAssert.isEmpty
- YUIArrayAssert.isNotEmpty
YUIDateAssert.js (requires YUIAssert.js, ported from YUI DateAssert.js)
YUIObjectAssert.js (requires YUIAssert.js and YUIObject.js, ported from YUI ObjectAssert.js)
- YUIObjectAssert.areEqual
- YUIObjectAssert.hasKey
- YUIObjectAssert.inheritsKey
- YUIObjectAssert.inheritsKeys
- YUIObjectAssert.ownsKey
- YUIObjectAssert.ownsKeys
- YUIObjectAssert.ownsNoKeys
- YUIObjectAssert.ownsOrInheritsKey
- YUIObjectAssert.ownsOrInheritsKeys
###Log functions
YUILog.js (requires YUILang.js and YUILog_config.js [src], ported from YUI yui.js)
(Ref. below for notes on using the YUI logging functions.)
###Type testing functions
YUILang.js (requires YUILang_config.js [src] for the .isArray
method, ported from YUI yui-lang.js)
- YUILang.isArray
- YUILang.isBoolean
- YUILang.isDate
- YUILang.isFunction
- YUILang.isNull
- YUILang.isNumber
- YUILang.isObject
- YUILang.isString
- YUILang.isValue
###Array functions
YUIArray.js (requires YUILang.js, ported from YUI yui-array.js)
- YUIArray.dedupe
- YUIArray.each
- YUIArray.hash
- YUIArray.indexOf
- YUIArray.numericSort
- YUIArray.some
- YUIArray.test
###Date functions
###Hash functions
YUIObject.js (requires YUILang.js and YUIArray.js for the .hasValue
method, ported from YUI yui-object.js)
- YUIObject.owns
- YUIObject.hasKey
- YUIObject.hasValue
- YUIObject.keys
- YUIObject.values
- YUIObject.size
- YUIObject.each
- YUIObject.some
- YUIObject.getValue
- YUIObject.setValue
- YUIObject.isEmpty
##YUILog Usage
.log()
log messages can be disabled with the boolean
YUILog_config.jsdebug
option - however
if a message is displayed using the .message()
function instead of .log()
,
then the message is logged to the console irrespective of the debug
setting.
The logInclude
and logExclude
config properties
should be literal objects with filename : [boolean]
values.
If the src
source filename argument is given as an argument to a log function
then if logInclude
is not empty, src
will have to be a true
property of
logInclude
for the log message to be displayed. If src
is a true
property of
logExclude
, then if it is not included as a logInclude
file, the log
message will be suppressed.
Additional config options include for a custom logging function (the current
code should support console.log
and Opera's browser console).
##Copyright
BSD License, as per the YUI Software License Agreement.
##Developers
Changelogs for the YUI3 source base from which the project is ported can be found on the YUI3 github repository:
- for the assert functions listed above (ported from /src/test/Assert.js, /src/test/AssertionError.js, /src/test/ComparisonFailure.js, /src/test/UnexpectedValue.js, /src/test/ArrayAssert.js, /src/test/DateAssert.js, /src/test/ObjectAssert.js) - changelog /src/test/README
- for the log, type test, array and hash functions (ported from /src/yui/yui.js, /src/yui/yui-lang.js, /src/yui/yui-array.js, /src/yui/yui-object.js) - changelog /src/yui/HISTORY.md.
As of 19 May 2012 the ported code is consistent with the producton release at that point, YUI 3.5.1.
##Alternative Libraries
Assert libraries:
assert.js - standalone port of node assert functions
should.js - node library
expect.js - based on should.js, standalone
chai - node and standalone, plugin architecture (inc. JQuery plugin)
Unit testing frameworks:
expectThat - CoffeeScript
jShould - QUnit extension
Jasmine - node module available with support for CoffeeScript
.net magazine Essential JavaScript: the top five testing libraries
jswiki 'Testing frameworks'
Wikipedia 'List of unit testing frameworks'
Log libraries:
log4javascript - based on log4j
log4js - API very similar to log4j
JavaScript Debug - wrapper for console.log
console.log-wrapper - console.log wrapper
(The concept of logging was popularized by Apache’s Log4J package for Java which has since become the common logging standard.)
##Changelog
22 October 2012
- Top 5 unit testing libraries article link added.
28 August 2012
- Reference to Jasmine unit testing framework added.
19 May 2012
- 'YUILang.config.useNativeES5' default to true (YUILang_config.js).
- YUIAssertX.js functions added (enhanced '.isNumber' and '.isArray' assertions, additional '.isDate' assert).
06 May 2012
- RC1 uploaded (minor code fixes may follow).