Validation Functions

Run-time test and validation functions. More...

Collaboration diagram for Validation Functions:

Files
file	validation.scad
	Methods for validating the results of functions.

Functions
function	validate (d, cv, t, ev, p=4, pf=false)
	Compare a computed test value with an known good result. More...
module	validate_log (t)
	Output text t to the test log. More...
module	validate_skip (fn)
	Output that function named fn has been skipped to the test log. More...
function	table_validate_init (tr, gr)
	Create data structure for related table validation functions. More...
function	table_validate_fmt (id, td, v1, v2, v3)
	Encode an entry for test table. More...
function	table_validate_get_ids (db)
	Return a list of test identifiers in db. More...
function	table_validate_get_ev (db, fn, id)
	Return the expected value. More...
function	table_validate_get_td (db, id)
	Return the test description. More...
function	table_validate_get_v1 (db, id)
	Return the test argument value 1. More...
function	table_validate_get_v2 (db, id)
	Return the test argument value 2. More...
function	table_validate_get_v3 (db, id)
	Return the test argument value 3. More...
module	table_validate_start (db, verbose=false)
	Test data structure db and output the start of test to the test log. More...
module	table_validate (db, id, fn, argc, fr, t="equals", p=6)
	Validate and log a test function return value against its expected value. More...
function	map_validate_init (m, fn)
	Create data structure for related map validation functions. More...
function	map_validate_fmt (id, td, ev, v1, v2, v3)
	Encode an entry for test map. More...
function	map_validate_get_ids (db)
	Return a list of test identifiers in db. More...
function	map_validate_get_fn (db)
	Return the test function name. More...
function	map_validate_get_td (db, id)
	Return the test description. More...
function	map_validate_get_ev (db, id)
	Return the expected value. More...
function	map_validate_get_v1 (db, id)
	Return the test argument value 1. More...
function	map_validate_get_v2 (db, id)
	Return the test argument value 2. More...
function	map_validate_get_v3 (db, id)
	Return the test argument value 3. More...
module	map_validate_start (db, verbose=false)
	Test data structure db and output the start of test to the test log. More...
module	map_validate (db, id, argc, fr, t="equals", p=6)
	Validate and log a test function return value against its expected value. More...

Variables
	validation_skip = [number_min, number_max, number_inf]
	Value signature assignment for log-value results table to skip a test.

Detailed Description

Run-time test and validation functions.

Requires:
include <omdl-base.scad>;
include <common/validation.scad>;

Function Documentation

map_validate()

module map_validate	(	db	,
		id	,
		argc	,
		fr	,
		t	= "equals",
		p	= 6
	)

Validate and log a test function return value against its expected value.

Parameters

db	<datastruct> An initialized validation map data structure.
id	<string> The test identifier.
argc	<integer> The number of arguments to retrieve from db.
fr	The value returned from the tested function.
t	<string | boolean> The validation type.
p	<number> A numerical precision for approximate comparisons.

See function validate() for more information on possible values for parameters t and p.

Map-based validation script

    include <omdl-base.scad>;
    include <common/validation.scad>;
 
    function fmt( id, td, ev, v1, v2, v3 ) = map_validate_fmt(id, td, ev, v1, v2, v3);
    function v1( db, id ) = map_validate_get_v1(db, id);
    function v2( db, id ) = map_validate_get_v2(db, id);
 
    map_test_defined_or =
    [
      fmt("t01", "Undefined", 1, undef, 1),
      fmt("t02", "A small value", eps, eps, 2),
      fmt("t03", "Infinity", number_inf, number_inf, 3),
      fmt("t04", "Max number", number_max, number_max, 4),
      fmt("t05", "Undefined list", [undef], [undef], 5),
      fmt("t06", "Short range", [0:9], [0:9], 6),
      fmt("t07", "Empty string", empty_str, empty_str, 7),
      fmt("t08", "Empty list", empty_lst, empty_lst, 8)
    ];
 
    db = map_validate_init( map_test_defined_or, "defined_or" );
    map_validate_start( db );
 
    for ( id = map_validate_get_ids( db ) )
      map_validate( db, id, 2, defined_or ( v1(db, id), v2(db, id) ) );
 
    // end_include

Map-based validation script output

ECHO: "[ omdl_test ] openscad version [2021, 1, 0]"
ECHO: "[ omdl_test ] defined_or()"
ECHO: "[ omdl_test ] t01 PASSED: 'defined_or(undef,1)=1'"
ECHO: "[ omdl_test ] t02 PASSED: 'defined_or(0.001,2)=0.001'"
ECHO: "[ omdl_test ] t03 PASSED: 'defined_or(inf,3)=inf'"
ECHO: "[ omdl_test ] t04 PASSED: 'defined_or(1e+308,4)=1e+308'"
ECHO: "[ omdl_test ] t05 PASSED: 'defined_or([undef],5)=[undef]'"
ECHO: "[ omdl_test ] t06 PASSED: 'defined_or([0 : 1 : 9],6)=[0 : 1 : 9]'"
ECHO: "[ omdl_test ] t07 PASSED: 'defined_or(,7)='"
ECHO: "[ omdl_test ] t08 PASSED: 'defined_or([],8)=[]'"

Definition at line 810 of file validation.scad.

Here is the call graph for this function:

map_validate_fmt()

function map_validate_fmt	(	id	,
		td	,
		ev	,
		v1	,
		v2	,
		v3
	)

Encode an entry for test map.

Parameters

id	<string> The test identifier.
td	<string> The test description.
ev	The test expect value.
v1	The test argument value 1.
v2	The test argument value 1.
v3	The test argument value 1.

Returns

<datastruct> An test map entry.

map_validate_get_ev()

function map_validate_get_ev	(	db	,
		id
	)

Return the expected value.

Parameters

db	<datastruct> An initialized validation map data structure.
id	<string> The test identifier.

Returns

The expect value.

Here is the caller graph for this function:

map_validate_get_fn()

function map_validate_get_fn

(

db

)

Return the test function name.

Parameters

db	<datastruct> An initialized validation map data structure.

Returns

<string> The test function name.

Here is the caller graph for this function:

map_validate_get_ids()

function map_validate_get_ids

(

db

)

Return a list of test identifiers in db.

Parameters

db	<datastruct> An initialized validation map data structure.

Returns

list of test identifiers.

map_validate_get_td()

function map_validate_get_td	(	db	,
		id
	)

Return the test description.

Parameters

db	<datastruct> An initialized validation map data structure.
id	<string> The test identifier.

Returns

<string> The test description for a given test id.

Here is the caller graph for this function:

map_validate_get_v1()

function map_validate_get_v1	(	db	,
		id
	)

Return the test argument value 1.

Parameters

db	<datastruct> An initialized validation map data structure.
id	<string> The test identifier.

Returns

The argument value 1.

Here is the caller graph for this function:

map_validate_get_v2()

function map_validate_get_v2	(	db	,
		id
	)

Return the test argument value 2.

Parameters

db	<datastruct> An initialized validation map data structure.
id	<string> The test identifier.

Returns

The argument value 2.

Here is the caller graph for this function:

map_validate_get_v3()

function map_validate_get_v3	(	db	,
		id
	)

Return the test argument value 3.

Parameters

db	<datastruct> An initialized validation map data structure.
id	<string> The test identifier.

Returns

The argument value 3.

Here is the caller graph for this function:

map_validate_init()

function map_validate_init	(	m	,
		fn
	)

Create data structure for related map validation functions.

Parameters

m	<map> The test data map.
fn	<string> The function name.

Returns

<datastruct> A structure used with the related map validation functions.

map_validate_start()

module map_validate_start	(	db	,
		verbose	= false
	)

Test data structure db and output the start of test to the test log.

Parameters

db	<datastruct> An initialized validation map data structure.
verbose	<boolean> Be more verbose.

Definition at line 699 of file validation.scad.

Here is the call graph for this function:

table_validate()

module table_validate	(	db	,
		id	,
		fn	,
		argc	,
		fr	,
		t	= "equals",
		p	= 6
	)

Validate and log a test function return value against its expected value.

Parameters

db	<datastruct> An initialized validation table data structure.
id	<string> The test identifier.
fn	<string> The function name.
argc	<integer> The number of arguments to retrieve from db.
fr	The value returned from the tested function.
t	<string | boolean> The validation type.
p	<number> A numerical precision for approximate comparisons.

See function validate() for more information on possible values for parameters t and p.

Table-based validation script

    include <omdl-base.scad>;
    include <common/validation.scad>;
 
    function fmt( id, td, v1, v2, v3 ) = table_validate_fmt(id, td, v1, v2, v3);
    function v1(db, id) = table_validate_get_v1(db, id);
    t = true; f = false; u = undef; s = validation_skip;
 
    // table: test values
    tbl_test_values =
    [
      fmt("t01", "The undefined value",        undef),
      fmt("t02", "A small decimal (epsilon)",  eps),
      fmt("t03", "The max number",             number_max),
      fmt("t04", "The invalid number nan",     0 / 0),
      fmt("t05", "The boolean true",           true),
      fmt("t06", "A string",                   "This is a longer string"),
      fmt("t07", "The empty string",           empty_str),
      fmt("t08", "The empty list",             empty_lst),
      fmt("t09", "A list of lists",            [[1,2,3], [4,5,6], [7,8,9]]),
      fmt("t10", "A range",                    [0:0.5:9])
    ];
 
    // table: expected results: use 's' to skip
    tbl_test_answers =
    [ // function       01 02 03 04 05 06 07 08 09 101
      ["is_bool",       f, f, f, f, f, f, f, f, f, t],
      ["is_string",     f, f, f, f, f, f, f, f, f, f],
      ["is_list",       f, f, f, f, f, f, f, f, f, f]
    ];
 
    db = table_validate_init( tbl_test_values, tbl_test_answers );
 
    table_validate_start( db );
    test_ids = table_validate_get_ids( db );
 
    for (id=test_ids) table_validate( db, id,   "is_bool", 1,   is_bool( v1(db, id) ) );
    for (id=test_ids) table_validate( db, id, "is_string", 1, is_string( v1(db, id) ) );
    for (id=test_ids) table_validate( db, id,   "is_list", 1,   is_list( v1(db, id) ) );
 
    // end_include

Table-based validation script output

ECHO: "[ omdl_test ] openscad version [2021, 1, 0]"
ECHO: "[ omdl_test ] t01 PASSED: 'is_bool(undef)=false'"
ECHO: "[ omdl_test ] t02 PASSED: 'is_bool(0.001)=false'"
ECHO: "[ omdl_test ] t03 PASSED: 'is_bool(1e+308)=false'"
ECHO: "[ omdl_test ] t04 PASSED: 'is_bool(nan)=false'"
ECHO: "[ omdl_test ] t05 FAILED: 'is_bool(true)=false'; got 'true', expected to equal 'false'. ---> "The boolean true""
ECHO: "[ omdl_test ] t06 PASSED: 'is_bool(This is a longer string)=false'"
ECHO: "[ omdl_test ] t07 PASSED: 'is_bool()=false'"
ECHO: "[ omdl_test ] t08 PASSED: 'is_bool([])=false'"
ECHO: "[ omdl_test ] t09 PASSED: 'is_bool([[1, 2, 3], [4, 5, 6], [7, 8, 9]])=false'"
ECHO: "[ omdl_test ] t10 FAILED: 'is_bool([0 : 0.5 : 9])=true'; got 'false', expected to equal 'true'. ---> "A range""
ECHO: "[ omdl_test ] t01 PASSED: 'is_string(undef)=false'"
ECHO: "[ omdl_test ] t02 PASSED: 'is_string(0.001)=false'"
ECHO: "[ omdl_test ] t03 PASSED: 'is_string(1e+308)=false'"
ECHO: "[ omdl_test ] t04 PASSED: 'is_string(nan)=false'"
ECHO: "[ omdl_test ] t05 PASSED: 'is_string(true)=false'"
ECHO: "[ omdl_test ] t06 FAILED: 'is_string(This is a longer string)=false'; got 'true', expected to equal 'false'. ---> "A string""
ECHO: "[ omdl_test ] t07 FAILED: 'is_string()=false'; got 'true', expected to equal 'false'. ---> "The empty string""
ECHO: "[ omdl_test ] t08 PASSED: 'is_string([])=false'"
ECHO: "[ omdl_test ] t09 PASSED: 'is_string([[1, 2, 3], [4, 5, 6], [7, 8, 9]])=false'"
ECHO: "[ omdl_test ] t10 PASSED: 'is_string([0 : 0.5 : 9])=false'"
ECHO: "[ omdl_test ] t01 PASSED: 'is_list(undef)=false'"
ECHO: "[ omdl_test ] t02 PASSED: 'is_list(0.001)=false'"
ECHO: "[ omdl_test ] t03 PASSED: 'is_list(1e+308)=false'"
ECHO: "[ omdl_test ] t04 PASSED: 'is_list(nan)=false'"
ECHO: "[ omdl_test ] t05 PASSED: 'is_list(true)=false'"
ECHO: "[ omdl_test ] t06 PASSED: 'is_list(This is a longer string)=false'"
ECHO: "[ omdl_test ] t07 PASSED: 'is_list()=false'"
ECHO: "[ omdl_test ] t08 FAILED: 'is_list([])=false'; got 'true', expected to equal 'false'. ---> "The empty list""
ECHO: "[ omdl_test ] t09 FAILED: 'is_list([[1, 2, 3], [4, 5, 6], [7, 8, 9]])=false'; got 'true', expected to equal 'false'. ---> "A list of lists""
ECHO: "[ omdl_test ] t10 PASSED: 'is_list([0 : 0.5 : 9])=false'"

Definition at line 552 of file validation.scad.

Here is the call graph for this function:

table_validate_fmt()

function table_validate_fmt	(	id	,
		td	,
		v1	,
		v2	,
		v3
	)

Encode an entry for test table.

Parameters

id	<string> The test identifier.
td	<string> The test description.
v1	The test argument value 1.
v2	The test argument value 1.
v3	The test argument value 1.

Returns

<datastruct> An test table entry.

table_validate_get_ev()

function table_validate_get_ev	(	db	,
		fn	,
		id
	)

Return the expected value.

Parameters

db	<datastruct> An initialized validation table data structure.
fn	<string> The function name.
id	<string> The test identifier.

Returns

The expect value.

Here is the caller graph for this function:

table_validate_get_ids()

function table_validate_get_ids

(

db

)

Return a list of test identifiers in db.

Parameters

db	<datastruct> An initialized validation table data structure.

Returns

list of test identifiers.

table_validate_get_td()

function table_validate_get_td	(	db	,
		id
	)

Return the test description.

Parameters

db	<datastruct> An initialized validation table data structure.
id	<string> The test identifier.

Returns

The test description.

Here is the caller graph for this function:

table_validate_get_v1()

function table_validate_get_v1	(	db	,
		id
	)

Return the test argument value 1.

Parameters

db	<datastruct> An initialized validation table data structure.
id	<string> The test identifier.

Returns

The test argument value 1.

Here is the caller graph for this function:

table_validate_get_v2()

function table_validate_get_v2	(	db	,
		id
	)

Return the test argument value 2.

Parameters

db	<datastruct> An initialized validation table data structure.
id	<string> The test identifier.

Returns

The test argument value 2.

Here is the caller graph for this function:

table_validate_get_v3()

function table_validate_get_v3	(	db	,
		id
	)

Return the test argument value 3.

Parameters

db	<datastruct> An initialized validation table data structure.
id	<string> The test identifier.

Returns

The test argument value 3.

Here is the caller graph for this function:

table_validate_init()

function table_validate_init	(	tr	,
		gr
	)

Create data structure for related table validation functions.

Parameters

tr	<table> The test data table rows.
gr	<table> The expected result data table rows.

Returns

<datastruct> A structure used with the related table validation functions.

table_validate_start()

module table_validate_start	(	db	,
		verbose	= false
	)

Test data structure db and output the start of test to the test log.

Parameters

db	<datastruct> An initialized validation table data structure.
verbose	<boolean> Be more verbose.

Definition at line 438 of file validation.scad.

Here is the call graph for this function:

validate()

function validate	(	d	,
		cv	,
		t	,
		ev	,
		p	= 4,
		pf	= false
	)

Compare a computed test value with an known good result.

Parameters

d	<string> A description.
cv	<value> A computed value to validate.
t	<string | boolean> The validation type.
ev	<value> The expected good value.
p	<number> A numerical precision for approximate comparisons.
pf	<boolean> Report result as pass or fail boolean value.

Returns

<string | boolean> Validation result indicating if the test passed or failed.

validation types	pass if (else fail)
"ae" | "almost"	cv almost equals ev
"eq" | "equals"	cv equals ev
"ne" | "not"	cv not equal to ev
"t" | "true" | true	cv is true
"f" | "false" | false	cv is false

Note

When performing an "almost" equal validation, the comparison precision is controlled by p. This specifies the number of digits of precision for each numerical comparison. A passing result indicates that cv equals ev to the number of decimal digits specified by p. The comparison is performed by the function almost_eq().

Validate function script

    include <omdl-base.scad>;
    include <common/validation.scad>;
 
    //
    // function to validate
    //
    function f1( x ) = (x == undef) ? 1 : 2;
 
    farg = undef;     // function test argument
    erv1 = 1;         // correct expected function result
    erv2 = 3;         // incorrect expected function result
 
    //
    // pass test example
    //
    log_type( "EXAMPLE 1", "pass test example" );
 
    pass_result = validate("test-a f1(farg)", f1(farg), "equals", erv1);
 
    if ( !validate(cv=f1(farg), t="equals", ev=erv1, pf=true) )
      log_warn( pass_result );
    else
      log_info( pass_result );
 
    //
    // fail test example
    //
    log_type( "EXAMPLE 2", "fail test example" );
 
    fail_result = validate("test-b f1(farg)", f1(farg), "equals", erv2);
 
    if ( !validate(cv=f1(farg), t="equals", ev=erv2, pf=true) )
      log_warn( fail_result );
    else
      log_info( fail_result );
 
    //
    // almost equal test example
    //
    log_type( "EXAMPLE 3", "almost equal test example" );
 
    tvae1 = [[90.001], [[45.009], true]];
    tvae2 = [[90.002], [[45.010], true]];
 
    log_type( "EXAMPLE 3", "almost equal to 3 digits" );
    log_info( validate("test-c", tvae1, "almost", tvae2, 3) );
 
    log_type( "EXAMPLE 3", "almost equal to 4 digits" );
    log_info( validate("test-d", tvae1, "almost", tvae2, 4) );
 
    // end_include

Validate function script output

ECHO: "[ EXAMPLE 1 ] pass test example"
ECHO: "[ INFO ] root(); PASSED: 'test-a f1(farg)'"
ECHO: "[ EXAMPLE 2 ] fail test example"
ECHO: 
ECHO: "root()"
ECHO: "##########################################################################"
ECHO: "# [ WARNING ] FAILED: 'test-b f1(farg)'; got '1', expected to equal '3'. #"
ECHO: "##########################################################################"
ECHO: "[ EXAMPLE 3 ] almost equal test example"
ECHO: "[ EXAMPLE 3 ] almost equal to 3 digits"
ECHO: "[ INFO ] root(); PASSED: 'test-c'"
ECHO: "[ EXAMPLE 3 ] almost equal to 4 digits"
ECHO: "[ INFO ] root(); FAILED: 'test-d'; got '[[90.001], [[45.009], true]]', expected to almost equal '[[90.002], [[45.01], true]]'. to 4 digits"

Here is the caller graph for this function:

validate_log()

module validate_log

(

t

)

Output text t to the test log.

Parameters

t	<string> A message to output to log.

Definition at line 323 of file validation.scad.

Here is the call graph for this function:

Here is the caller graph for this function:

validate_skip()

module validate_skip

(

fn

)

Output that function named fn has been skipped to the test log.

Parameters

fn	<string> The name of the skipped function.

Definition at line 329 of file validation.scad.

Here is the call graph for this function: