The 1am Reference Manual

Table of Contents

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

The 1am Reference Manual

This is the 1am Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Tue Jan 09 13:01:17 2018 GMT+0.


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

1 Introduction

1am

A minimal testing framework for Common Lisp.

Synopsis

The entire API consists of: test, is, signals, run, and *tests*.

(defpackage :example (:use :cl :1am))
(in-package :example)

(test foo-test
  (is (= 1 1))
  (is (zerop 0)))

(test bar-test
  (signals simple-error
    (error "bar!")))

Running:

CL-USER> (in-package :example)
#<PACKAGE "EXAMPLE">

EXAMPLE> (run) ; run all tests
BAR-TEST.
FOO-TEST..
Success: 2 tests, 3 checks.

EXAMPLE> (foo-test) ; tests are just functions
FOO-TEST..
Success: 1 test, 2 checks.

EXAMPLE> (run '(bar-test)) ; run particular tests
BAR-TEST.
Success: 1 test, 1 check.

EXAMPLE> (setf *tests* '(foo-test)) ; set the default tests to run
(FOO-TEST)
EXAMPLE> (run)
FOO-TEST..
Success: 1 test, 2 checks.

Overview

1am is tiny (~60 lines of code), has no dependencies, and will be stable for the foreseeable future. It was originally written for large multi-threaded test suites where the complexity of popular testing frameworks caused problems. The philosophy of 1am is that simple is better. 1am is especially tailored for fixing bugs that are difficult to reproduce.

Workflow

Instead of a hierarchy of test suites, 1am has a flat list of tests in *tests*. When a test is compiled, it is added to *tests*. A typical workflow might be:

  1. Run all tests to verify they pass.

  2. Set *tests* to nil, then compile specific tests that are relevant to some feature, perhaps writing new tests in the process. Now *tests* contains only those tests.

  3. When changes for that feature are complete, recompile all tests to confirm those changes, which will add them back to *tests*.

  4. Run all tests again to check that nothing is messed up.

API


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 1am

Author

James M. Lawrence <llmjjmll@gmail.com>

License

MIT

Description

A minimal testing framework.

Source

1am.asd (file)

Component

1am.lisp (file)


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

3 Files

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


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

3.1 Lisp


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

3.1.1 1am.asd

Location

1am.asd

Systems

1am (system)


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

3.1.2 1am/1am.lisp

Parent

1am (system)

Location

1am.lisp

Packages

1am

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 1am

Source

1am.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

5 Definitions

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


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

5.1 Exported definitions


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

5.1.1 Special variables

Special Variable: *tests*

A list of tests; the default argument to ‘run’.

Package

1am

Source

1am.lisp (file)


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

5.1.2 Macros

Macro: is FORM

Assert that ‘form’ evaluates to non-nil.

Package

1am

Source

1am.lisp (file)

Macro: signals CONDITION &body BODY

Assert that ‘body’ signals a condition of type ‘condition’.

Package

1am

Source

1am.lisp (file)

Macro: test NAME &body BODY

Define a test function and add it to ‘*tests*’.

Package

1am

Source

1am.lisp (file)


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

5.1.3 Functions

Function: run &optional TESTS

Run each test in the sequence ‘tests’. Default is ‘*tests*’.

Package

1am

Source

1am.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *failed-random-state*
Package

1am

Source

1am.lisp (file)

Special Variable: *pass-count*
Package

1am

Source

1am.lisp (file)

Special Variable: *running*
Package

1am

Source

1am.lisp (file)


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

5.2.2 Functions

Function: %run FN TEST-COUNT
Package

1am

Source

1am.lisp (file)

Function: %shuffle VECTOR
Package

1am

Source

1am.lisp (file)

Function: %signals EXPECTED FN
Package

1am

Source

1am.lisp (file)

Function: call-test NAME FN
Package

1am

Source

1am.lisp (file)

Function: call-with-random-state FN
Package

1am

Source

1am.lisp (file)

Function: passed ()
Package

1am

Source

1am.lisp (file)

Function: report TEST-COUNT PASS-COUNT
Package

1am

Source

1am.lisp (file)

Function: shuffle SEQUENCE
Package

1am

Source

1am.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   1  
F   L  
Index Entry  Section

1
1am.asd: The 1am<dot>asd file
1am/1am.lisp: The 1am/1am<dot>lisp file

F
File, Lisp, 1am.asd: The 1am<dot>asd file
File, Lisp, 1am/1am.lisp: The 1am/1am<dot>lisp file

L
Lisp File, 1am.asd: The 1am<dot>asd file
Lisp File, 1am/1am.lisp: The 1am/1am<dot>lisp file

Jump to:   1  
F   L  

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

A.2 Functions

Jump to:   %  
C   F   I   M   P   R   S   T  
Index Entry  Section

%
%run: Internal functions
%shuffle: Internal functions
%signals: Internal functions

C
call-test: Internal functions
call-with-random-state: Internal functions

F
Function, %run: Internal functions
Function, %shuffle: Internal functions
Function, %signals: Internal functions
Function, call-test: Internal functions
Function, call-with-random-state: Internal functions
Function, passed: Internal functions
Function, report: Internal functions
Function, run: Exported functions
Function, shuffle: Internal functions

I
is: Exported macros

M
Macro, is: Exported macros
Macro, signals: Exported macros
Macro, test: Exported macros

P
passed: Internal functions

R
report: Internal functions
run: Exported functions

S
shuffle: Internal functions
signals: Exported macros

T
test: Exported macros

Jump to:   %  
C   F   I   M   P   R   S   T  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*failed-random-state*: Internal special variables
*pass-count*: Internal special variables
*running*: Internal special variables
*tests*: Exported special variables

S
Special Variable, *failed-random-state*: Internal special variables
Special Variable, *pass-count*: Internal special variables
Special Variable, *running*: Internal special variables
Special Variable, *tests*: Exported special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   1  
P   S  
Index Entry  Section

1
1am: The 1am system
1am: The 1am package

P
Package, 1am: The 1am package

S
System, 1am: The 1am system

Jump to:   1  
P   S