How to use the test environment

Architecture

The codebase for Day includes an object DAYx with methods for running tests in browser and node.js environments. The majority of this code facilitates running tests. The methods which implement particular features are coded in javascript independently of the main code-base and are loaded into the test environment at run-time. Scripts are text files that call the methods with varying inputs and expected outputs. In short, a lot of 'given foo do we get bar?'

This document describes how to set-up and run tests

Scripts

Scripts are plain text files with the extension .testScript collected into tests/scripts directory. The name of the file will be used as a menu option in the test console, so try to make it easy to interpret.

The general format is

METHOD( Input arg[, Input arg]) Expected result [#Comment]

Comments always start with # and may start in column one to be a general comment
Input arguments are split by commas (Commas and closing brackets not allowed)
Special values are allowed for the expected result:
- = which is shorthand for the same as the input
- [TODAY] which indicates the result has to be checked manually because although technically a fail it may be correct given that 'today' varies. (For example TOSTRING(Today,d2m2y4) will give a different result depending on when it is run.)
- @YEAR and @TODAY will get substituted by current values

As well as true tests there are two special methods with no expected results:

SETCONFIG	This alters the configuration/environment on the fly. Directly set config with SETCONFIG(KEY,VALUE) Or execute a method of DAYc For example SETCONFIG(SetLimitToUnixExtended)
EXPLAIN	Describes the environment and internals of any Day object. It reports the internals of an optional DAYo object followed by main environment settings. Example use EXPLAIN(2 Jan 13 BC)

Methods

// Implements the ToString function DAYx.AddLibraryTest( 'TOSTRING', "Implements ToString method", "(day string, format string)", "string output", function(TestData){ var aa,d,r,ok,ds; try{ aa = TestData[1].split(','); if(aa.length != 2){throw "TOSTRING needs two arguments";} d = new DAYo(aa[0]); r = d.ToString(aa[1].trim()); ok= StartsWith(TestData[2],r); }catch(e){ r = 'EXCEPTION:<br>'+String(e)+'<br>' + DAYx._ErrorPlace(e); ok = false; } return [ok,TestData,r,null]; } );

Methods are written in Javascript. See the example
There can be more than one method per file.
The five arguments to the AddLibraryTest method are:
1. Method name. Always capitalised.
2. Brief description of test
3. Input arguments simply described
4. Sort of output expected
5. Function to do the dirty deed
  - Typically only the first handful of lines after the try{ will change from one method to another.
  - TestData is an array, being a parsed version of the script line.
    [1] is arguments eg foo,bar
    [2] is expected result
  - The array returned is [pass/fail, original script line, actual result, comment].

Method files are of the form anyName.js but must be in tests/methods. They are searched-out at run-time and added to the method library.

Test console

You can call DAYx.Output() with a label and array of values arguments to insert anything into the results listing. Think of it as a custom version of console.log() but you can see your intermediate debugging data together with the final result. Example DAYx.Output('SomeVars',[foo,bar,baz]);

The purpose of the test console is to run a script or part of a script in order to home-in on some issue during development. The first thing should be a list of scripts (using their file names) to pick.

Often it is convenient to run a few or even just one script line. The controls beneath the list of scripts allow you to do this.

Passed tests are shown in green like this.
Failed tests are shown in red like this.
Non-tests are shown in blue like this. Note that when running a subset of tests all the SETCONFIGs up to the start line will be executed. This ensures that the environment is consistent.
Failed but possibly OK after examination ([TODAY] lines) are shown in yellow like this.

Batch testing with node

This uses exactly the same scripts and methods libraries as the interactive browser version.

~ $ cd .../tools/node ~.../tools/node $ node dt.js

Called without arguments dt.js will run all the scripts it can find.
The full usage is node dt [<Script_name> [<from_line>] [<to_line>]]

You might have looked at the dt.js code to see that DAYx.RunTestsInNode is the hardworking handmaiden. This fetches the script file then runs through it.

Output goes to the console and to a summary html document tests/results/JsDate-fails.htm This has clickable links to passes and fails which are displayed in the format you'd expect to see in the interactive tester.