##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:

• YUIAssert.areEqual
• YUIAssert.areNotEqual
• YUIAssert.areSame
• YUIAssert.areNotSame

Boolean:

• YUIAssert.isFalse
• YUIAssert.isTrue

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:

• YUIAssert.throwsError

YUIAssertX.js (requires YUIAssert.js, YUILang.js)

• YUIAssertX.isArray
• YUIAssertX.isNumber
• YUIAssertX.isDate

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)

• YUIDateAssert.datesAreEqual
• YUIDateAssert.timesAreEqual

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)

• YUILog.log
• YUILog.message

(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

YUILangX.js

• YUILangX.datesAreEqual
• YUILangX.timesAreEqual

###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 logIncludefor 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).