The simplet Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The simplet Reference Manual

This is the simplet Reference Manual, version 1.2.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 16:39:13 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

simplet

Simple test runner in Common Lisp.

Getting Started in simplet

Portability

I believe it works in all implementations, but I only tested the one I use, which is the SBCL.

Dependencies

No dependency.

Download and installation

1 - Download simplet system

By quicklisp:

IN PROGRESS...

or directly from github:

git clone https://github.com/noloop/simplet.git

2 - Install simplet

By quicklisp:

IN PROGRESS...

or directly from asdf:

(asdf:load-system :simplet)

Note: Remember to configure asdf to find your directory where you downloaded the libraries (asdf call them "systems") above, if you do not know how to make a read at: https://common-lisp.net/project/asdf/asdf/Configuring-ASDF-to-find-your-systems.html or https://lisp-lang.org/learn/writing-libraries.

Create suite and test

CL-USER> (suite "Suite 1"
                (test "Test one equal one" #'(lambda () (= 1 1)))
                (test "Test two equal two" #'(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
                (test "Test three equal three" #'(lambda () (= 3 3))))

Run tests

CL-USER> (run)
#...Simplet...#

Test one equal one: T
Test two equal two: T
Suite 1: T

Test three equal three: T
Suite 2: T

Runner result: T

NIL

You also can getting an string of run, instead of printing on REPL:

CL-USER> (run :return-string-p t)
NIL

Suites and tests PENDING(or also called TODO)

It's simple to add a suite or test PENDING. To the suites, just do not add tests to it. To the tests just do not add a test function. Suites and tests PENDING do not make the runner result fail, however they are marked with PENDING instead of T. See the example below:

CL-USER> (suite "Suite 1"
                (test "Test one equal one" #'(lambda () (= 1 1)))
                (test "Test two equal two"))
CL-USER> (suite "Suite 2")

CL-USER> (run)
#...Simplet...#

Test one equal one: T
Test two equal two: PENDING
Suite 1: T

Suite 2: PENDING

Runner result: T

NIL

Suites and tests only/skip

For suites only:

CL-USER> (suite-only "Suite 1"
                     (test "Test one equal one" #'(lambda () (= 1 1)))
                     (test "Test two equal two" #'(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
                (test "Test three equal three" #'(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test one equal one: T
Test two equal two: T
Suite 1: T

Runner result: T

NIL

For tests only:

CL-USER> (suite "Suite 1"
                 (test-only "Test one equal one" #'(lambda () (= 1 1)))
                 (test "Test two equal two" #'(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
                (test-only "Test three equal three" #'(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test one equal one: T
Suite 1: T

Test three equal three: T
Suite 2: T

Runner result: T

NIL

For suites skip:

CL-USER> (suite-skip "Suite 1"
                     (test "Test one equal one" #'(lambda () (= 1 1)))
                     (test "Test two equal two" #'(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
                 (test "Test three equal three" #'(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test three equal three: T
Suite 2: T

Runner result: T

NIL

For tests skip:

CL-USER> (suite "Suite 1"
                 (test-skip "Test one equal one" #'(lambda () (= 1 1)))
                 (test "Test two equal two" #'(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
                 (test-skip "Test three equal three" #'(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test two equal two: T
Suite 1: T

Suite 2: T

Runner result: T

NIL

Beware of traps when mixing only and skip:

CL-USER> (suite-skip "Suite 1"
                     (test-only "Test one equal one" #'(lambda () (= 1 1)))
                     (test "Test two equal two" #'(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
                 (test "Test three equal three" #'(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Runner result: T

NIL

ASDF integration

Do not forget to add :defsystem-depends-on (:simplet-asdf) to your-app.asd system definition file, this will enable:test-file in the :components. The class :test-file is similar to:file except it will be loaded only when call asdf:test-system. See an example below:

(defsystem :your-app
  ;; ...
  :in-order-to ((test-op (test-op your-app/test))))

(defsystem :your-app/test
  :author "your <your@youremail.com>"
  :depends-on (:your-app :simplet)
  :defsystem-depends-on (:simplet-asdf)
  :components ((:module "test"
                :components
                ((:test-file "your-app-test"))))
  :perform (test-op (op c)
                    (progn (funcall (intern #.(string :run-simplet-asdf) :simplet) c)
                           (symbol-call :simplet '#:run))))
                           

To run tests with ASDF:

(asdf:test-system :your-app)

Limitations

API

function (suite description &rest tests)

function (suite-only description &rest tests)

function (suite-skip description &rest tests)

function (test description &optional fn)

function (test-only description &optional fn)

function (test-skip description &optional fn)

function (run &key return-string-p)


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 simplet

Maintainer

noloop <noloop@zoho.com>

Author

noloop <noloop@zoho.com>

Home Page

https://github.com/noloop/simplet

Source Control

(:git "git@github.com:noloop/simplet.git")

Bug Tracker

https://github.com/noloop/simplet/issues

License

GPLv3

Description

Simple test runner in Common Lisp.

Long Description

# simplet

### _Simple test runner in Common Lisp._

## Getting Started in simplet

### Portability

I believe it works in all implementations, but I only tested the one I use, which is the SBCL.

### Dependencies

No dependency.

### Download and installation

**1 - Download simplet system**

By quicklisp:

“‘
IN PROGRESS...
“‘

or directly from github:

“‘
git clone https://github.com/noloop/simplet.git
“‘
**2 - Install simplet**

By quicklisp:

“‘
IN PROGRESS...
“‘

or directly from asdf:

“‘lisp
(asdf:load-system :simplet)
“‘

_**Note: Remember to configure asdf to find your directory where you downloaded the libraries (asdf call them "systems") above, if you do not know how to make a read at: https://common-lisp.net/project/asdf/asdf/Configuring-ASDF-to-find-your-systems.html or https://lisp-lang.org/learn/writing-libraries.**_

## Create suite and test

“‘lisp
CL-USER> (suite "Suite 1"
(test "Test one equal one" #’(lambda () (= 1 1)))
(test "Test two equal two" #’(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
(test "Test three equal three" #’(lambda () (= 3 3))))
“‘
## Run tests

“‘lisp
CL-USER> (run)
#...Simplet...#

Test one equal one: T
Test two equal two: T
Suite 1: T

Test three equal three: T
Suite 2: T

Runner result: T

NIL
“‘

You also can getting an string of run, instead of printing on REPL:

“‘lisp
CL-USER> (run :return-string-p t)
NIL
“‘
## Suites and tests PENDING(or also called TODO)

It’s simple to add a suite or test PENDING. To the suites, just do not add tests to it. To the tests just do not add a test function. Suites and tests PENDING do not make the runner result fail, however they are marked with PENDING instead of T. See the example below:

“‘lisp
CL-USER> (suite "Suite 1"
(test "Test one equal one" #’(lambda () (= 1 1)))
(test "Test two equal two"))
CL-USER> (suite "Suite 2")

CL-USER> (run)
#...Simplet...#

Test one equal one: T
Test two equal two: PENDING
Suite 1: T

Suite 2: PENDING

Runner result: T

NIL
“‘

## Suites and tests only/skip

For suites only:

“‘lisp
CL-USER> (suite-only "Suite 1"
(test "Test one equal one" #’(lambda () (= 1 1)))
(test "Test two equal two" #’(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
(test "Test three equal three" #’(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test one equal one: T
Test two equal two: T
Suite 1: T

Runner result: T

NIL
“‘

For tests only:

“‘lisp
CL-USER> (suite "Suite 1"
(test-only "Test one equal one" #’(lambda () (= 1 1)))
(test "Test two equal two" #’(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
(test-only "Test three equal three" #’(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test one equal one: T
Suite 1: T

Test three equal three: T
Suite 2: T

Runner result: T

NIL
“‘

For suites skip:

“‘lisp
CL-USER> (suite-skip "Suite 1"
(test "Test one equal one" #’(lambda () (= 1 1)))
(test "Test two equal two" #’(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
(test "Test three equal three" #’(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test three equal three: T
Suite 2: T

Runner result: T

NIL
“‘

For tests skip:

“‘lisp
CL-USER> (suite "Suite 1"
(test-skip "Test one equal one" #’(lambda () (= 1 1)))
(test "Test two equal two" #’(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
(test-skip "Test three equal three" #’(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Test two equal two: T
Suite 1: T

Suite 2: T

Runner result: T

NIL
“‘

Beware of traps when mixing only and skip:

“‘lisp
CL-USER> (suite-skip "Suite 1"
(test-only "Test one equal one" #’(lambda () (= 1 1)))
(test "Test two equal two" #’(lambda () (= 2 2))))
CL-USER> (suite "Suite 2"
(test "Test three equal three" #’(lambda () (= 3 3))))

CL-USER> (run)
#...Simplet...#

Runner result: T

NIL
“‘
## ASDF integration

Do not forget to add ‘:defsystem-depends-on (:simplet-asdf)‘ to ‘your-app.asd‘ system definition file, this will enable‘:test-file‘ in the ‘:components‘. The class ‘:test-file‘ is similar to‘:file‘ except it will be loaded only when call ‘asdf:test-system‘. See an example below:

“‘lisp
(defsystem :your-app
;; ...
:in-order-to ((test-op (test-op your-app/test))))

(defsystem :your-app/test
:author "your <your@youremail.com>"
:depends-on (:your-app :simplet)
:defsystem-depends-on (:simplet-asdf)
:components ((:module "test"
:components
((:test-file "your-app-test"))))
:perform (test-op (op c)
(progn (funcall (intern #.(string :run-simplet-asdf) :simplet) c)
(symbol-call :simplet ’#:run))))

“‘

To run tests with ASDF:

“‘lisp
(asdf:test-system :your-app)
“‘

## Limitations

* Whitout cacth error
* Solely synchronous tests
* Whitout fixtures
* Whitout timeout
* Without recursives suites
* Without assertion libraries integration
* Not possible execution of tests whitout suites(because not contain the concept of root-suite.)

## API

function **(suite description &rest tests)**

function **(suite-only description &rest tests)**

function **(suite-skip description &rest tests)**

function **(test description &optional fn)**

function **(test-only description &optional fn)**

function **(test-skip description &optional fn)**

function **(run &key return-string-p)**

Version

1.2.0

Source

simplet.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 simplet/src

Parent

simplet (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 simplet.asd

Location

simplet.asd

Systems

simplet (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 simplet/src/asdf.lisp

Parent

src (module)

Location

src/asdf.lisp

Packages

simplet-asdf

Exported Definitions
Internal Definitions

*system-test-files* (special variable)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 simplet/src/package.lisp

Dependency

asdf.lisp (file)

Parent

src (module)

Location

src/package.lisp

Packages

noloop.simplet


Previous: , Up: Lisp files   [Contents][Index]

4.1.4 simplet/src/simplet.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/simplet.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 simplet-asdf

Source

asdf.lisp (file)

Use List
Exported Definitions
Internal Definitions

*system-test-files* (special variable)


Previous: , Up: Packages   [Contents][Index]

5.2 noloop.simplet

Source

package.lisp (file)

Nickname

simplet

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Functions

Function: run &key RETURN-STRING-P
Package

noloop.simplet

Source

simplet.lisp (file)

Function: run-simplet-asdf SYSTEM-DESIGNATOR

Runs a testing ASDF system.

Package

simplet-asdf

Source

asdf.lisp (file)

Function: suite DESCRIPTION &rest TESTS
Package

noloop.simplet

Source

simplet.lisp (file)

Function: suite-only DESCRIPTION &rest TESTS
Package

noloop.simplet

Source

simplet.lisp (file)

Function: suite-skip DESCRIPTION &rest TESTS
Package

noloop.simplet

Source

simplet.lisp (file)

Function: test DESCRIPTION &optional FN
Package

noloop.simplet

Source

simplet.lisp (file)

Function: test-only DESCRIPTION &optional FN
Package

noloop.simplet

Source

simplet.lisp (file)

Function: test-skip DESCRIPTION &optional FN
Package

noloop.simplet

Source

simplet.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Classes

Class: test-file ()
Package

simplet-asdf

Source

asdf.lisp (file)

Direct superclasses

cl-source-file (class)

Direct methods
  • perform (method)
  • perform (method)
  • output-files (method)
  • input-files (method)

Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *system-test-files*
Package

simplet-asdf

Source

asdf.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Functions

Function: clear-suites ()
Package

noloop.simplet

Source

simplet.lisp (file)

Function: collect-suites-only SUITES
Package

noloop.simplet

Source

simplet.lisp (file)

Function: collect-tests-only TESTS
Package

noloop.simplet

Source

simplet.lisp (file)

Function: create-list-suite-result DESCRIPTION TESTS ONLY SKIP
Package

noloop.simplet

Source

simplet.lisp (file)

Function: create-suite DESCRIPTION TESTS &key ONLY SKIP
Package

noloop.simplet

Source

simplet.lisp (file)

Function: create-test DESCRIPTION FN &key ONLY SKIP
Package

noloop.simplet

Source

simplet.lisp (file)

Function: get-suites ()
Package

noloop.simplet

Source

simplet.lisp (file)

Function: reporter RUNNER-RESULT &key RETURN-STRING-P
Package

noloop.simplet

Source

simplet.lisp (file)

Function: run-suites SUITES
Package

noloop.simplet

Source

simplet.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M   S  
Index Entry  Section

F
File, Lisp, simplet.asd: The simplet<dot>asd file
File, Lisp, simplet/src/asdf.lisp: The simplet/src/asdf<dot>lisp file
File, Lisp, simplet/src/package.lisp: The simplet/src/package<dot>lisp file
File, Lisp, simplet/src/simplet.lisp: The simplet/src/simplet<dot>lisp file

L
Lisp File, simplet.asd: The simplet<dot>asd file
Lisp File, simplet/src/asdf.lisp: The simplet/src/asdf<dot>lisp file
Lisp File, simplet/src/package.lisp: The simplet/src/package<dot>lisp file
Lisp File, simplet/src/simplet.lisp: The simplet/src/simplet<dot>lisp file

M
Module, simplet/src: The simplet/src module

S
simplet.asd: The simplet<dot>asd file
simplet/src: The simplet/src module
simplet/src/asdf.lisp: The simplet/src/asdf<dot>lisp file
simplet/src/package.lisp: The simplet/src/package<dot>lisp file
simplet/src/simplet.lisp: The simplet/src/simplet<dot>lisp file

Jump to:   F   L   M   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   F   G   R   S   T  
Index Entry  Section

C
clear-suites: Internal functions
collect-suites-only: Internal functions
collect-tests-only: Internal functions
create-list-suite-result: Internal functions
create-suite: Internal functions
create-test: Internal functions

F
Function, clear-suites: Internal functions
Function, collect-suites-only: Internal functions
Function, collect-tests-only: Internal functions
Function, create-list-suite-result: Internal functions
Function, create-suite: Internal functions
Function, create-test: Internal functions
Function, get-suites: Internal functions
Function, reporter: Internal functions
Function, run: Exported functions
Function, run-simplet-asdf: Exported functions
Function, run-suites: Internal functions
Function, suite: Exported functions
Function, suite-only: Exported functions
Function, suite-skip: Exported functions
Function, test: Exported functions
Function, test-only: Exported functions
Function, test-skip: Exported functions

G
get-suites: Internal functions

R
reporter: Internal functions
run: Exported functions
run-simplet-asdf: Exported functions
run-suites: Internal functions

S
suite: Exported functions
suite-only: Exported functions
suite-skip: Exported functions

T
test: Exported functions
test-only: Exported functions
test-skip: Exported functions

Jump to:   C   F   G   R   S   T  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*system-test-files*: Internal special variables

S
Special Variable, *system-test-files*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   N   P   S   T  
Index Entry  Section

C
Class, test-file: Exported classes

N
noloop.simplet: The noloop<dot>simplet package

P
Package, noloop.simplet: The noloop<dot>simplet package
Package, simplet-asdf: The simplet-asdf package

S
simplet: The simplet system
simplet-asdf: The simplet-asdf package
System, simplet: The simplet system

T
test-file: Exported classes

Jump to:   C   N   P   S   T