2021-02-05

(sph test)

automated code testing with composable modules.

part of sph-lib

library description

procedure-wrap: false/procedure:{test-proc test-name -> proc}

# define-test-module

test modules are typical modules/libraries that export only one procedure named "execute". the syntax defined here abstracts the definition.

modules are used to give test modules a separated scope in which test module dependencies are integrated.

there might be alternatives to using modules - for example evaluating files in custom environments that use the import statement. but modules seem, because of their

possible composition, like the best solution at this point.

the syntax defined here must be available in the environment in which the test module is loaded.

to archieve this, the definition is initially evaluated in the top-level environment (loading/definition) and the module object is later resolved using environment* (resolving)

# data structures:

test-result: ([group-name] test-result ...)/vector

# syntax

test-settings-default-custom :: [any:unquoted-key any:value] ... -> list

test-list :: symbol:name/(symbol:name any:io-data ...) ... -> ((symbol procedure [arguments expected] ...) ...)

define-test

  :: (name [arguments expected settings]) body ...

  :: name procedure body ...

  define a procedure with the name test-{name} and the arity expected by the default evaluators

define-procedure-tests :: symbol:name symbol/literal-list

  define a variable with tests that can be executed with test-execute-procedures.

  resolves procedures by name and normalises the test specification

test-execute-procedures-lambda :: test-list-arguments ... -> procedure:{settings -> test-result}

  create a procedure that executes procedure tests corresponding to test-spec.

  can be used as the last expression in a test module

test-lambda

  :: symbol:formals/([arguments expected settings]) body ... -> procedure

  creates a normalised test procedure with the correct arity

assert-and :: [optional-title] expression ... -> vector:test-result

  creates a successful test result if all given expressions or assertions are successful test results or true

assert-equal :: [optional-title] expected expression -> vector:test-result

module name

(sph test)

exported bindings

syntax: assert-and
syntax: assert-equal optional-title expected expr
syntax: assert-test-result title expr continue
string/false expression expression -> true/test-result:failure
assertions create test-result vectors only on failure
syntax: assert-true optional-title expr
syntax: define-procedure-tests name test-spec ...
-> ((symbol procedure any ...) ...)
syntax: define-test
syntax: define-test-module
using eval because exporting bindings created with define created by syntax was not working
variable: sph-test-description
procedure: test-create-result [success? title assert-title index result arguments expected] ->
boolean string string integer any list any -> vector:test-result
procedure: test-execute-module settings name ->
list (symbol ...) -> test-result
procedure: test-execute-modules settings module-names ->
list list -> test-result
procedure: test-execute-modules-by-prefix #:settings module-names ... ->
execute all test modules whose module name has the one of the given module name prefixes.
\"path-search\" restricts the path where to search for test-modules.
\"search-type\" does not execute modules that exactly match the module name prefix (where the module name prefix resolves to a regular file)
procedure: test-execute-procedures settings source ->
list ((symbol:name procedure:test-proc any:data-in/out ...) ...) -> test-result
syntax: test-execute-procedures-lambda test-spec ...
syntax: test-lambda
syntax: test-list test-spec ...
procedure: test-module-name-from-files a ->
string -> list/error
procedure: test-result-success? a ->
variable: test-settings-default
syntax: test-settings-default-custom key/value ...
procedure: test-settings-default-custom-by-list key/value ->
[key value] ... -> list
get the default test settings, with values possibly set to the values given with \"key/value\"