The nst Reference Manual

4.1.1 nst/nst.asd

Source

nst.asd.

Parent Component

nst (system).

ASDF Systems

nst.

Packages

nst-asd.

Internals

nst-doc (function).

---

4.1.2 nst/core/package.lisp

Source

nst.asd.

Parent Component

core (module).

Packages

• nst.
• nst-name-use-in-packages.

---

4.1.3 nst/core/utils.lisp

Dependency

package.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Internals

• cdr-or-nil (function).
• def-hashtable-fns (macro).
• eql-for-sigdigits (function).
• log10 (macro).
• named-function (macro).
• no-effect (function).
• sig-place (function).
• symbol-or-car (function).

---

4.1.4 nst/core/errors.lisp

Dependency

package.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Internals

• actual-value (reader method).
• criterion-missing-mandatory-argument (condition).
• criterion-name (reader method).
• debug-for-fail (condition).
• define-nst-error (macro).
• expected-form (reader method).
• group (reader method).
• group (reader method).
• no-nst-groups-in-package (condition).
• no-such-nst-group (condition).
• no-such-nst-test (condition).
• not-expected-form (condition).
• nst-deprecation-warning-mixin (condition).
• nst-error (condition).
• nst-hard-deprecation (condition).
• nst-soft-deprecation (condition).
• nst-soft-keyarg-deprecation (condition).
• old-name (reader method).
• package-of (reader method).
• replacement (reader method).
• required-keyarg (reader method).
• soft-dep-warning (function).
• test (reader method).
• with-nst-control-handlers (macro).
• with-retry (macro).

---

4.1.5 nst/core/interrupt.lisp

Dependency

package.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Internals

• +keyboard-interrupt-class+ (constant).
• handler-bind-interruptable (macro).

---

4.1.6 nst/core/permuter.lisp

Dependency

package.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• initialize-instance (method).
• print-object (method).

Internals

• fmt-permuter (generic function).
• get-unassigned (function).
• has-next (reader method).
• next-permutation (function).
• permuter (class).
• permuter-frame (class).
• qw (special variable).
• qwerty (special variable).
• relax-stack (function).
• tighten-stack (function).
• whittlable (function).
• whittle-relaxed-stack (function).

---

4.1.7 nst/core/globals.lisp

Dependencies

• errors.lisp (file).
• utils.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• *debug-on-error* (special variable).
• *debug-on-fail* (special variable).
• *default-report-verbosity* (special variable).
• *nst-output-stream* (special variable).

Internals

• *default-debug-config* (special variable).
• *default-debug-protect* (special variable).
• *generate-backtraces* (special variable).
• *nst-check-internal-name* (special variable).
• *nst-check-user-name* (special variable).
• *nst-context* (special variable).
• *nst-context-evaluable* (special variable).
• *nst-debug* (special variable).
• *nst-group-name* (special variable).
• *nst-group-shown* (special variable).
• *nst-report-driver* (special variable).
• *nst-stack* (special variable).
• *nst-verbosity* (special variable).
• apply-debug-options (macro).
• apply-default-debug-options (macro).
• assemble-protected-option-values (function).
• at-verbosity (macro).
• base-name (generic function).
• format-at-verbosity (macro).
• nst-repl-property-display (generic function).
• nst-repl-property-doc (generic function).
• nst-repl-property-encode (generic function).
• princ-filled-text (function).
• protect-nst-config (macro).
• restore-protected-option-values (function).
• run-debug-options (function).
• set-nst-property (generic function).
• show-nst-property (generic function).
• with-output-for-verbosity (macro).

---

4.1.8 nst/core/context.lisp

Dependencies

• package.lisp (file).
• globals.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Internals

• context-layer (class).
• criterion (reader method).
• (setf criterion) (writer method).
• criterion-args (reader method).
• (setf criterion-args) (writer method).
• criterion-context-layer (class).
• get-display-context-layers (function).
• get-local-criterion-context (function).
• given-stack (reader method).
• (setf given-stack) (writer method).
• show-context-layer (generic function).
• with-context-layer (macro).
• with-criterion-context-layer (macro).

---

4.1.9 nst/core/artifacts.lisp

Dependency

globals.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Packages

nst-name-usage.

Internals

• +name-uses+ (special variable).
• +results-record+ (special variable).
• all-uses (function).
• artifact-recorder (function).
• blurb-one-name-use (function).
• copy-name-use (function).
• copy-result-stats (function).
• executable-uses (function).
• make-name-use (function).
• make-result-stats (function).
• name-use (function).
• name-use (structure).
• name-use-fixtures (reader).
• (setf name-use-fixtures) (writer).
• name-use-groups (reader).
• (setf name-use-groups) (writer).
• name-use-last-use (reader).
• (setf name-use-last-use) (writer).
• name-use-name (reader).
• (setf name-use-name) (writer).
• name-use-p (function).
• name-use-package-p (reader).
• (setf name-use-package-p) (writer).
• name-use-tests (reader).
• (setf name-use-tests) (writer).
• note-name-invocation (function).
• record-name-use (function).
• record-package-use (function).
• result-stats (structure).
• result-stats-elapsed-time (reader).
• (setf result-stats-elapsed-time) (writer).
• result-stats-erring (reader).
• (setf result-stats-erring) (writer).
• result-stats-failing (reader).
• (setf result-stats-failing) (writer).
• result-stats-p (function).
• result-stats-passing (reader).
• (setf result-stats-passing) (writer).
• result-stats-tests (reader).
• (setf result-stats-tests) (writer).
• result-stats-timestamp (reader).
• (setf result-stats-timestamp) (writer).
• result-stats-warning (reader).
• (setf result-stats-warning) (writer).
• trace-group (generic function).
• trace-results (function).
• trace-test (generic function).

---

4.1.10 nst/core/group.lisp

Dependencies

• artifacts.lisp (file).
• globals.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

def-test-group (macro).

Internals

• *group-records* (special variable).
• base-name (method).
• copy-group-record (function).
• group-record (function).
• (setf group-record) (function).
• group-record (structure).
• group-record-anon-fixture-forms (reader).
• (setf group-record-anon-fixture-forms) (writer).
• group-record-aspirational (reader).
• (setf group-record-aspirational) (writer).
• group-record-documentation (reader).
• (setf group-record-documentation) (writer).
• group-record-eachtest-cleanup-thunk (reader).
• (setf group-record-eachtest-cleanup-thunk) (writer).
• group-record-eachtest-setup-thunk (reader).
• (setf group-record-eachtest-setup-thunk) (writer).
• group-record-fixtures-cleanup-thunk (reader).
• (setf group-record-fixtures-cleanup-thunk) (writer).
• group-record-fixtures-setup-thunk (reader).
• (setf group-record-fixtures-setup-thunk) (writer).
• group-record-given-fixtures (reader).
• (setf group-record-given-fixtures) (writer).
• group-record-include-groups (reader).
• (setf group-record-include-groups) (writer).
• group-record-name (reader).
• (setf group-record-name) (writer).
• group-record-p (function).
• group-record-tests (reader).
• (setf group-record-tests) (writer).
• group-record-withfixtures-cleanup-thunk (reader).
• (setf group-record-withfixtures-cleanup-thunk) (writer).
• group-record-withfixtures-setup-thunk (reader).
• (setf group-record-withfixtures-setup-thunk) (writer).
• make-group-record (function).
• package-groups (function).
• pull-test-name-list (function).
• separate-group-subforms (function).
• test-record (function).
• (setf test-record) (function).
• trace-group (method).

---

4.1.11 nst/core/check.lisp

Dependencies

• context.lisp (file).
• interrupt.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• check-criterion-on-form (function).
• check-criterion-on-value (function).
• def-criterion (macro).
• def-criterion-alias (macro).
• def-criterion-unevaluated (macro).
• def-form-criterion (macro).
• def-values-criterion (macro).

Internals

• apply-criterion (generic function).
• build-continue-check-expr (function).
• continue-check (function).
• decompose-arg-values-lambda-list (function).
• def-check-alias (macro).
• def-control-check (macro).
• def-value-check (macro).
• extract-parameters (function).
• returning-criterion-config-error (macro).
• returning-test-error (macro).

---

4.1.12 nst/core/fixture.lisp

Dependencies

• errors.lisp (file).
• globals.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• def-fixtures (macro).
• with-fixtures (macro).

Internals

• *fixture-bindings* (special variable).
• *fixture-letlist* (special variable).
• *fixture-record* (special variable).
• apply-fixture (function).
• apply-fixtures (function).
• base-name (method).
• copy-fixture-record (function).
• decode-caching-decls (function).
• decode-fixture-syntax (function).
• fixture-bindings (function).
• (setf fixture-bindings) (function).
• fixture-letlist (function).
• (setf fixture-letlist) (function).
• fixture-record (function).
• (setf fixture-record) (function).
• fixture-record (structure).
• fixture-record-bindings-list (reader).
• (setf fixture-record-bindings-list) (writer).
• fixture-record-bound-names (reader).
• (setf fixture-record-bound-names) (writer).
• fixture-record-cache-flush (reader).
• (setf fixture-record-cache-flush) (writer).
• fixture-record-documentation (reader).
• (setf fixture-record-documentation) (writer).
• fixture-record-function (reader).
• (setf fixture-record-function) (writer).
• fixture-record-name (reader).
• (setf fixture-record-name) (writer).
• fixture-record-p (function).
• flush-fixture-cache (function).
• make-fixture-record (function).
• open-fixture (function).

---

4.1.13 nst/core/test-def.lisp

Dependencies

• errors.lisp (file).
• globals.lisp (file).
• group.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

def-test (macro).

Internals

• base-name (method).
• copy-test-record (function).
• decode-defcheck-name-and-args (function).
• def-check (macro).
• make-test-record (function).
• test-is-aspirational (function).
• test-record (structure).
• test-record-aspirational (reader).
• (setf test-record-aspirational) (writer).
• test-record-aspirational-supp (reader).
• (setf test-record-aspirational-supp) (writer).
• test-record-cleanup (reader).
• (setf test-record-cleanup) (writer).
• test-record-criterion (reader).
• (setf test-record-criterion) (writer).
• test-record-documentation (reader).
• (setf test-record-documentation) (writer).
• test-record-finish (reader).
• (setf test-record-finish) (writer).
• test-record-fixtures (reader).
• (setf test-record-fixtures) (writer).
• test-record-forms (reader).
• (setf test-record-forms) (writer).
• test-record-group (reader).
• (setf test-record-group) (writer).
• test-record-name (reader).
• (setf test-record-name) (writer).
• test-record-p (function).
• test-record-results (reader).
• (setf test-record-results) (writer).
• test-record-setup (reader).
• (setf test-record-setup) (writer).
• test-record-special-fixture-names (reader).
• (setf test-record-special-fixture-names) (writer).
• test-record-startup (reader).
• (setf test-record-startup) (writer).
• trace-test (method).

---

4.1.14 nst/core/status.lisp

Dependencies

• globals.lisp (file).
• artifacts.lisp (file).
• check.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• add-error (function).
• add-failure (function).
• add-info (function).
• add-warning (generic function).
• emit-failure (macro).
• emit-success (macro).
• emit-warning (macro).
• make-error-report (function).
• make-failure-report (function).
• make-success-report (function).
• make-warning-report (function).
• wrap-thrown-lisp-warning (function).

Internals

• %make-check-result (function).
• add-thrown-error (function).
• all-groups-report (function).
• all-package-report (function).
• all-tests-report (function).
• apply-check-note-formatter (function).
• apply-formatter (function).
• calibrate-check-result (function).
• check-note (structure).
• check-note-args (reader).
• (setf check-note-args) (writer).
• check-note-context (reader).
• (setf check-note-context) (writer).
• check-note-format (reader).
• (setf check-note-format) (writer).
• check-note-p (function).
• check-note-stack (reader).
• (setf check-note-stack) (writer).
• check-note-type-string (generic function).
• check-result (macro).
• check-result (structure).
• check-result-check-name (reader).
• (setf check-result-check-name) (writer).
• check-result-elapsed-time (function).
• (setf check-result-elapsed-time) (function).
• check-result-erring (function).
• (setf check-result-erring) (function).
• check-result-errors (reader).
• (setf check-result-errors) (writer).
• check-result-failing (function).
• (setf check-result-failing) (function).
• check-result-failures (reader).
• (setf check-result-failures) (writer).
• check-result-group-name (reader).
• (setf check-result-group-name) (writer).
• check-result-info (reader).
• (setf check-result-info) (writer).
• check-result-p (function).
• check-result-passing (function).
• (setf check-result-passing) (function).
• check-result-skipped (reader).
• (setf check-result-skipped) (writer).
• check-result-tests (reader).
• (setf check-result-tests) (writer).
• check-result-timestamp (function).
• (setf check-result-timestamp) (function).
• check-result-warning (function).
• (setf check-result-warning) (function).
• check-result-warnings (reader).
• (setf check-result-warnings) (writer).
• copy-check-note (function).
• copy-check-result (function).
• copy-error-check-note (function).
• copy-group-result (function).
• copy-multi-results (function).
• copy-package-result (function).
• count-nonnulls (macro).
• emit-error (macro).
• error-check-note (structure).
• error-check-note-args (function).
• (setf error-check-note-args) (function).
• error-check-note-context (function).
• (setf error-check-note-context) (function).
• error-check-note-error (reader).
• (setf error-check-note-error) (writer).
• error-check-note-format (function).
• (setf error-check-note-format) (function).
• error-check-note-p (function).
• error-check-note-stack (function).
• (setf error-check-note-stack) (function).
• finish-multiple-report (function).
• fixture-binding-error-note (function).
• format-for-warning (generic function).
• get-report-from-names (function).
• group-report (function).
• group-result (structure).
• group-result-check-results (reader).
• (setf group-result-check-results) (writer).
• group-result-elapsed-time (function).
• (setf group-result-elapsed-time) (function).
• group-result-erring (function).
• (setf group-result-erring) (function).
• group-result-failing (function).
• (setf group-result-failing) (function).
• group-result-group-name (reader).
• (setf group-result-group-name) (writer).
• group-result-p (function).
• group-result-passing (function).
• (setf group-result-passing) (function).
• group-result-tests (function).
• (setf group-result-tests) (function).
• group-result-timestamp (function).
• (setf group-result-timestamp) (function).
• group-result-warning (function).
• (setf group-result-warning) (function).
• interesting-result-p (function).
• make-and-calibrate-check-result (function).
• make-check-note (function).
• make-check-result (function).
• make-config-error (function).
• make-error-check-note (function).
• make-error-note (function).
• make-group-result (function).
• make-multi-results (function).
• make-package-result (function).
• make-skipped-report (function).
• multi-results (structure).
• multi-results-elapsed-time (function).
• (setf multi-results-elapsed-time) (function).
• multi-results-erring (function).
• (setf multi-results-erring) (function).
• multi-results-failing (function).
• (setf multi-results-failing) (function).
• multi-results-group-reports (reader).
• (setf multi-results-group-reports) (writer).
• multi-results-p (function).
• multi-results-package-reports (reader).
• (setf multi-results-package-reports) (writer).
• multi-results-passing (function).
• (setf multi-results-passing) (function).
• multi-results-stats-source (reader).
• (setf multi-results-stats-source) (writer).
• multi-results-system (reader).
• (setf multi-results-system) (writer).
• multi-results-test-reports (reader).
• (setf multi-results-test-reports) (writer).
• multi-results-tests (function).
• (setf multi-results-tests) (function).
• multi-results-timestamp (function).
• (setf multi-results-timestamp) (function).
• multi-results-warning (function).
• (setf multi-results-warning) (function).
• multiple-report (function).
• nst-dump (function).
• package-report (function).
• package-result (structure).
• package-result-elapsed-time (function).
• (setf package-result-elapsed-time) (function).
• package-result-erring (function).
• (setf package-result-erring) (function).
• package-result-failing (function).
• (setf package-result-failing) (function).
• package-result-group-results (reader).
• (setf package-result-group-results) (writer).
• package-result-p (function).
• package-result-package-name (reader).
• (setf package-result-package-name) (writer).
• package-result-passing (function).
• (setf package-result-passing) (function).
• package-result-tests (function).
• (setf package-result-tests) (function).
• package-result-timestamp (function).
• (setf package-result-timestamp) (function).
• package-result-warning (function).
• (setf package-result-warning) (function).
• report-details (function).
• report-group (function).
• report-interesting (function).
• report-multiple (function).
• report-package (function).
• report-summary (function).
• report-test (function).
• result-summary (generic function).
• test-report (function).
• use-stats-from (function).

---

4.1.15 nst/core/runner.lisp

Dependencies

• interrupt.lisp (file).
• test-def.lisp (file).
• group.lisp (file).
• status.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Internals

• *implicit-group-choice* (special variable).
• core-run-test (function).
• get-test-record-specials (function).
• run-group (function).
• run-group-record (function).
• run-group-test (function).
• run-group-tests (function).
• run-group-tests-fixtures-thunk (function).
• run-package (function).
• run-test (function).
• run-test-fixtures-thunk (function).
• run-test-inst (function).
• wrap-fixture-name-specials (function).

---

4.1.16 nst/core/criteria.lisp

Dependencies

• errors.lisp (file).
• interrupt.lisp (file).
• permuter.lisp (file).
• check.lisp (file).
• status.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Internals

• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• apply-criterion (method).
• refine-package-symbol-desigs (function).

---

4.1.17 nst/core/process.lisp

Dependencies

• errors.lisp (file).
• interrupt.lisp (file).
• check.lisp (file).
• status.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• *assert-eq-format-string* (special variable).
• *assert-eql-format-string* (special variable).
• *assert-equal-format-string* (special variable).
• *assert-equalp-format-string* (special variable).
• *assert-nonnil-format-string* (special variable).
• *assert-not-eq-format-string* (special variable).
• *assert-not-eql-format-string* (special variable).
• *assert-not-equal-format-string* (special variable).
• *assert-not-equalp-format-string* (special variable).
• *assert-null-format-string* (special variable).
• *assert-zero-format-string* (special variable).
• assert-criterion (macro).
• assert-eq (function).
• assert-eql (function).
• assert-equal (function).
• assert-equalp (function).
• assert-non-nil (function).
• assert-not-eq (function).
• assert-not-eql (function).
• assert-not-equal (function).
• assert-not-equalp (function).
• assert-null (function).
• assert-zero (function).
• def-binary-negated-predicate-assert (macro).
• def-binary-predicate-assert (macro).
• def-eval-test (macro).
• def-unary-negated-predicate-assert (macro).
• def-unary-predicate-assert (macro).

Internals

• apply-criterion (method).
• apply-criterion (method).
• assert-criterion-fn (function).
• assertion-failure-args (reader method).
• assertion-failure-fatal (reader method).
• assertion-failure-formatter (reader method).
• nst-assertion-condition (condition).
• nst-assertion-failure (condition).
• nst-assertion-result (reader method).
• nst-assertion-result-check (condition).

---

4.1.18 nst/core/command.lisp

Dependencies

• globals.lisp (file).
• status.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Packages

nst-artifact-lookup-package.

Public Interface

nst-cmd (macro).

Internals

• *last-repl-call* (special variable).
• +nst-repl-commands+ (special variable).
• +nst-repl-properties+ (special variable).
• consider-repl-call-save (generic function).
• def-nst-interactive-command (macro).
• def-nst-property (macro).
• flag-filter (function).
• nst-arg-names (generic function).
• nst-long-help (generic function).
• nst-repl-property-display (method).
• nst-repl-property-display (method).
• nst-repl-property-display (method).
• nst-repl-property-doc (method).
• nst-repl-property-doc (method).
• nst-repl-property-doc (method).
• nst-repl-property-encode (method).
• nst-repl-property-encode (method).
• nst-repl-property-encode (method).
• nst-short-help (generic function).
• prep-arg-names-help (generic function).
• run-command-actual (generic function).
• run-nst-command (function).
• set-nst-property (method).
• set-nst-property (method).
• set-nst-property (method).
• show-nst-property (method).
• show-nst-property (method).
• show-nst-property (method).

---

4.1.19 nst/core/xml.lisp

Dependency

status.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Internals

• *default-xml-pprint-dispatch* (special variable).
• check-note-type-string (method).
• elapsed-time-to-string (function).
• junit-header (function).
• pprint-cdata-string (function).
• pprint-xml (function).
• symbol-to-junit-name (function).
• timestamp-to-string (function).
• with-pprint-cdata (macro).
• with-xml-tagged-pprint-logical-block (macro).

---

4.1.20 nst/core/junit.lisp

Dependency

xml.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• junit-results-by-group (function).
• nst-junit-dump (generic function).

Internals

• *char-escapes* (special variable).
• *entities* (special variable).
• junit-group-result (generic function).
• nst-xml-dump (function).
• string-escaped (function).

---

4.1.21 nst/core/sampling.lisp

Dependency

check.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• *max-compound-structure-depth* (special variable).
• arbitrary (generic function).
• compound-structure (macro).
• def-arbitrary-instance-type (macro).

Internals

• *current-compound-structure-depth* (special variable).
• *default-character-range* (special variable).
• *max-auto-array-rank* (special variable).
• +arbitrary-generable-types+ (special variable).
• +scalar-generable-types+ (special variable).
• apply-criterion (method).
• arbitrary-by-spec (generic function).
• arbitrary-generable-types (function).
• arbitrary-grounded-type (generic function).
• coin-flip (macro).
• domain (reader method).
• generate-sample (function).
• keyword-args (reader method).
• low-biased-natnum (function).
• mid-biased-natnum (function).
• pick-from-sequence (function).
• unknown-arbitrary-domain (condition).

---

4.1.22 nst/core/method.lisp

Dependencies

• status.lisp (file).
• check.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Public Interface

• (setf class-name) (writer method).
• class-name (reader method).
• def-test-generic (macro).
• def-test-method (macro).
• def-test-method-criterion (macro).
• nst-results (method combination).

Internals

• *test-methods* (special variable).
• apply-criterion (method).
• check-result-union (function).
• collect-test-generics (function).
• decode-def-test-generic-body (function).
• invoke-test-methods (function).
• method-context-layer (class).
• method-name (reader method).
• (setf method-name) (writer method).
• object (reader method).
• (setf object) (writer method).
• show-context-layer (method).
• with-method-context-layer (macro).

---

4.1.23 nst/core/interfaces.lisp

Dependencies

• check.lisp (file).
• status.lisp (file).

Source

nst.asd.

Parent Component

core (module).

Packages

nst-control-api.

Internals

def-bundle-package (macro).

---

6.1.1 Special variables

Special Variable: *assert-eq-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-eql-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-equal-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-equalp-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-nonnil-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-not-eq-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-not-eql-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-not-equal-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-not-equalp-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-null-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *assert-zero-format-string* ¶

Package

nst.

Source

process.lisp.

Special Variable: *debug-on-error* ¶

User variable =*debug-on-error*=: if non-nil, will break into the Lisp REPL debugger upon encountering an unexpected error. If nil, will record the error and continue with other tests.

Package

nst.

Source

globals.lisp.

Special Variable: *debug-on-fail* ¶

User variable =*debug-on-fail*=: if non-nil, will break into the Lisp REPL debugger upon encountering a test which fails. If nil, will record the failure and continue with other tests. This variable is useful inspecting the dynamic environment under which a test was evaluated.

Package

nst.

Source

globals.lisp.

Special Variable: *default-report-verbosity* ¶

User variable =*default-report-verbosity*= determines the default value for =*nst-verbosity*= when printing reports (2 by default).

Package

nst.

Source

globals.lisp.

Special Variable: *max-compound-structure-depth* ¶

The =*max-compound-structure-depth*= variable sets the maximum nesting depth of compound data structures: beyond that depth, =scalar= rather than =t= is the default element generator. This restriction does not apply to explicitly specified element types, only to the use of defaults.

Package

nst.

Source

sampling.lisp.

Special Variable: *nst-output-stream* ¶

Determines the output stream to which NST should print its output (=*standard-output*= by default).

Package

nst.

Source

globals.lisp.

---

6.1.2 Macros

Macro: assert-criterion (key-args criterion-expr &rest value-exprs) ¶

The =assert-criterion= macro asserts that an NST criterion should pass. #+begin_example
(assert-criterion ( [ :msg-format FORMAT-STRING ]
[ :msg-args FORMAT-ARGUMENTS ]
[ :fatal FLAG [
[ :fail-on-warning FLAG ] )
FORM
...
FORM)
#+end_example
- msg-format :: Format string used to build the label of the restart point. - msg-args :: Format arguments used to build the label of the restart point. - fatal :: If non-nil, a failure of this assertion indicates that execution of the test forms should be aborted.
- fail-on-warning :: If non-nil, then an NST result which includes a warning indicates failure of this assertion.

Package

nst.

Source

process.lisp.

Macro: compound-structure (&body forms) ¶

The =compound-structure= macro wraps substructure which should be considered compound for the limits set by =*max-compound-structure-depth*=.

Package

nst.

Source

sampling.lisp.

Macro: def-arbitrary-instance-type (type-expr &body technique) ¶

New type specifications for invariant-testing. are defined with the =def-arbitrary-instance-type= macro.
#+begin_example
(def-arbitrary-instance-type ( SPEC-NAME [ :params FORMALS ]
[ :scalar BOOL ]
[ :key KEY ] )
FORM
FORM
...
FORM)
#+end_example
- =formals= :: Formal parameter definition used to pass subcomponent types. - =scalar= :: When a non-null value is provided for the =:scalar= argument, the new specifier is taken to be generable by the =:scalar= specification.
#+begin_example
(def-arbitrary-instance-type (ratio :scalar t)
(/ (arbitrary ’integer)
(let ((raw (arbitrary (find-class ’integer)))) (cond
((< raw 0) raw)
(t (+ 1 raw))))))
#+end_example
- =key= :: The =:key= argument gives a list of keyword arguments which may accompany the new specification. For the =cons= type, keyword arguments allow specifications for the left and right components: #+begin_example
(def-arbitrary-instance-type
(cons :key ((car t car-supp-p) (cdr t cdr-supp-p))) (compound-structure
(when (and (not car-supp-p)
(>= *current-compound-structure-depth* *max-compound-structure-depth*))
(setf car ’scalar))
(when (and (not cdr-supp-p)
(>= *current-compound-structure-depth* *max-compound-structure-depth*))
(setf cdr ’scalar))
(cons (arbitrary car) (arbitrary cdr)))) #+end_example
- =form= :: Construct and return (as if through =progn= the arbtrary instance.

Package

nst.

Source

sampling.lisp.

Macro: def-binary-negated-predicate-assert (assert-fn predicate default-message &rest keyargs &key message-defvar) ¶

Macro =def-binary-negated-predicate-assert= uses the negated result of a binary predicate as the basis for an assertion function just as =def-unary-negated-predicate-assert= uses the negated result of a unary predicate. This macro’s arguments are just as for =def-unary-predicate-assert=.

Package

nst.

Source

process.lisp.

Macro: def-binary-predicate-assert (assert-fn predicate default-message &key message-defvar doc-state-flag pred-name) ¶

Macro =def-binary-predicate-assert= uses a binary predicate as the basis for an assertion function just as =def-unary-predicate-assert= uses a unary predicate. This macro’s arguments are just as for =def-unary-predicate-assert=.

Package

nst.

Source

process.lisp.

Macro: def-criterion ((name args-formals values-formals) &body forms) ¶

The =def-criterion= macro defines a new criterion for use in NST tests.
These criteria definitions are like generic function method definitions with two
sets of formal parameters: the forms provided as the actual parameters of the
criterion itself, and the values arising from the evaluation of the forms under
test.
#+begin_example
(def-criterion (name criterion-lambda-list values-lambda-list)
[ doc-string )
form
form
...
form)
#+end_example

- name :: Name of the criterion.
- criterion-lambda-list :: Lambda list for the arguments to the criterion. Optionally, the first element of the list is a symbol specifying the parameter-passing semantics for the criterion arguments: =:values= for call-by-value, or =:forms for call-by-name (the default). The list may include the keywords =&key=, =&optional=, =&body= and =&rest= but may not use =&whole= or =&environment=. Apart from this restriction, in the former case the list may be any ordinary lambda list as for =defun=, and in the latter case the list may be any macro lambda list as for =defmacro=.
- values-lambda-list :: Lambda list for the forms under test. Optionally, the first element of the list is a symbol specifying the parameter-passing semantics for the criterion arguments: :values for call-by-value (the default), or :form for call-by-name. In the former case, the list may include the keywords =&key=, =&optional=, =&body= and =&rest=, but not =&whole= or =&environment=; apart from that restriction, list may be any ordinary lambda list as for =defun=. In the latter case, the remainder of the list must contain exactly one symbol, to which a form which would evaluate to the values under test will be bound. If the criterion ignores the values, then instead of a lambda list, this argument may be the symbol =:ignore=. On many platforms, listing a dummy parameter which is then =declare=d =ignore= or =ignorable= will produce a style warning: the body of a =def-criterion= should not be assumed to correspond directly to the body of a =defmethod=; in general there will be surrounding =destructuring-bind=s.
- documentation :: An optional documentation string for the criterion.
- form :: The body of the criterion definition should return a test result report contructed with the =make-success-report=, etc. functions.
Examples:
#+begin_example
(def-criterion (:true () (bool))
(if bool
(make-success-report)
(make-failure-report :format "Expected non-null, got: ~s"
:args (list bool))))

(def-criterion (:eql (target) (actual))
(if (eql (eval target) actual)
(make-success-report)
(make-failure-report :format "Not eql to value of ~s"
:args (list target))))
#+end_example

Package

nst.

Source

check.lisp.

Macro: def-criterion-alias ((name . args-formals) docstring-or-form &optional form) ¶

The simplest mechanism for defining a new criterion involves simply
defining one criterion to rewrite as another using =def-criterion-alias=. #+begin_example
(def-criterion-alias (name (:seq arg))
[ doc-string ]
expansion)
#+end_example
The body of the expansion should be a Lisp form which, when evaluated, returns an S-expression quoting the new criterion which the rewrite should produce. The =arg= are passed as for Lisp macros: they are not evaluated and are most typically comma-inserted into a backquoted result. For example: #+begin_example
(def-criterion-alias (:forms-eq) ‘(:predicate eq))
(def-criterion-alias (:symbol name) ‘(:eq ’,name))
#+end_example

Package

nst.

Source

check.lisp.

Macro: def-criterion-unevaluated ((name args-formals forms-formal &key ignore-forms) &body forms) ¶

The =def-criterion-unevaluated= macro is deprecated as of NST 2.1.2. It was consolidated into the =def-criterion= macro.

Replace:
#+begin_example
(def-criterion-unevaluated name (pattern ... pattern) name
BODY)
#+end_example
with:
#+begin_example
(def-criterion name (:forms pattern ... pattern)
(:form name)
BODY)
#+end_example

Package

nst.

Source

check.lisp.

Macro: def-eval-test (name-or-name-and-args &rest forms) ¶

The =def-eval-test= macro abbreviates a call to =def-test= with a single =:eval= criterion. Its arguments are just as for =def-test= and =:eval=. #+begin_example
(def-eval-test (NAME [ :group GROUP-NAME ]
[ :setup FORM ]
[ :cleanup FORM ]
[ :startup FORM ]
[ :finish FORM ]
[ :fixtures (FIXTURE ... FIXTURE) ]
[ :documentation STRING ]
[ :check-warnings FLAG ]
[ :muffle-warnings FLAG ]
[ :attempt-continue FLAG ]
[ :force-continue FLAG ] )
FORM
...
FORM)

(def-eval-test NAME
FORM
...
FORM)
#+end_example

Package

nst.

Source

process.lisp.

Macro: def-fixtures (name (&key uses assumes special outer inner documentation cache setup cleanup startup finish export-names export-bound-names export-fixture-name) &body bindings) ¶

Fixtures are data structures and values which may be referred to by name during testing. NST provides the ability to use fixtures across multiple tests and test groups, and to inject fixtures into the runtime namespace for debugging. A set of fixtures is defined using the =def-fixtures= macro: #+begin_example
(def-fixtures fixture-name ( [ :outer FORM ]
[ :inner FORM ]
[ :setup FORM ]
[ :cleanup FORM ]
[ :startup FORM ]
[ :finish FORM ]
[ :documentation STRING ]
[ :cache FLAG ]
[ :export-names FLAG ]
[ :export-fixture-name FLAG ]
[ :export-bound-names FLAG ] )
( [ ( [ :cache FLAG ] ) ] NAME [ FORM ] )
...
( [ ( [ :cache FLAG ] ) ] NAME [ FORM ] ) )
#+end_example
- fixture-name :: The name to be associated with this set of fixtures.
- inner :: List of declarations to be made inside the let-binding of
names of any use of this fixture. Do not include the "declare" keyword here; NST adds these declarations to others, including a special declaration of all bound names.
- outer :: List of declarations to be made outside the let-binding of
names of any use of this fixture.
- documentation :: A documentation string for the fixture set.
- special :: Specifies a list of names which should be declared
=special= in the scope within which this set’s fixtures are
evaluated. The individual names are taken to be single variable names. Each =(:fixture NAME)= specifies all of the names of the given fixture set. This declaration is generally optional under most platforms, but can help supress spurious warnings. Note that
multiple =NAMEs= may be listed, and these lists and the bare
names may be intermixed. If only one name or fixture is
specified, it need not be placed in a list
- export-fixture-name :: When non-nil, the fixture name will be added
to the list of symbols exported by the current package.
- export-bound-names :: When non-nil, the names bound by this fixture
will be added to the list of symbols exported by the current package.
- export-names :: When non-nil, sets the default value to t for the
two options above.
- cache :: If specified with the group options, when non-nil, the
fixture values are cached at their first use, and re-applied at subsequent fixture application rather than being recalculated.

When a fixture is attached to a test or test group, each =NAME=
defined in that fixture becomes available in the body of that test or
group as if =let*= bound to the corresponding =FORM=. A fixture in
one set may refer back to other fixtures in the same set (again as
=let*=) but forward references are not allowed.

The four arguments =startup=, =finish=, =setup= and =cleanup= specify
forms which are run everytime the fixture is applied to a group or
test. The =startup= (respectively =finish=) form is run before
fixtures are bound (after their bindings are released). These forms
are useful, for example, to initialize a database connection from
which the fixture values are drawn. The =setup= form is run after inclusion of names from fixture sets, but before any tests from the
group. The =cleanup= form is normally run after the test completes,
but while the fixtures are still in scope. Normally, the =cleanup=
form will not be run if the =setup= form raises an error, and the
=finish= form will not be run if the =startup= form raises an error; although the user is able to select (perhaps unwisely) a restart which disregards the error.

The names of a fixture and the names it binds can be exported from the package where the fixture is defined using the =export-bound-names=
and =export-fixture-name= arguments. The default value of both is the value of =export-names=, whose default value is =nil=.

The =cache= option, if non-nil, directs NST to evaluate a fixture’s
form one single time, and re-use the resulting value on subsequent applications of the fixture. Note that if this value is mutated by
the test cases, test behavior may become unpredictable! However this option can considerably improve performance when constant-valued
fixtures are applied repeatedly. Caching may be set on or off (the
default is off) for the entire fixture set, and the setting may vary
for individual fixtures.

Examples of fixture definitions:
#+begin_example
(def-fixtures f1 ()
(c 3)
(d ’asdfg))
(def-fixtures f2 (:special ((:fixture f1)))
(d 4)
(e ’asdfg)
(f c))
(def-fixtures f3 ()
((:cache t) g (ackermann 1 2))
((:cache nil) h (factorial 5)))
#+end_example

To cause a side-effect among the evaluation of a fixture’s name definitions, =nil= can be provided as a fixture name. In uses of the fixture, NST will replace =nil= with a non-interned symbol; in documentation such as form =:whatis=, any =nil=s are omitted.

Package

nst.

Source

fixture.lisp.

Macro: def-form-criterion ((name args-formals form-formal) &rest forms) ¶

The =def-form-criterion= macro was deprecated as of NST 1.3.0. /Code using =def-form-criterion= in any but the simplest ways is very likely to fail./ Use =def-criterion= instead.

Package

nst.

Source

check.lisp.

Macro: def-test (name-or-name-and-args criterion &rest forms) ¶

Individual unit tests are encoded with the =def-test= form: #+begin_example
(def-test NAME ( [ :group GROUP-NAME ]
[ :setup FORM ]
[ :cleanup FORM ]
[ :startup FORM ]
[ :finish FORM ]
[ :fixtures (FIXTURE FIXTURE ... FIXTURE) ]
[ :aspirational FLAG ]
[ :documentation STRING ] )
criterion
FORM ... FORM)

(def-test NAME criterion &body (:seq FORM))
#+end_example
The =SETUP=, =CLEANUP=, =STARTUP=, =FINISH= and =FIXTURES= are just as for fixtures and test groups, but apply only to the one test. The =CRITERION= is a list or symbol specifying the properties which should hold for
the =FORM=s.

When a test is not enclosed within a group body, a group name must be provided by the =GROUP= option. When a test is enclosed within
a group body, the =GROUP= option is not required, but if
provided it must agree with the group name.

When there are no =SETUP=, =CLEANUP=, =STARTUP=, =FINISH= or =FIXTURES= arguments, the =NAME= may be given without parentheses. Likewise, any criterion consisting of a single symbol, e.g. =(:pass)=, may be abbreviated as just the symbol without the parentheses, e.g. =:pass=.

The =:documentation= form provides a documentation string in
the standard Lisp sense. Since documentation strings are stored
against names, and since the same name can be used for several tests
(so long as they are all in different packages), documentation strings
on tests may not be particularly useful.

An =aspirational= test is one which verifies some part of an API or code contract which may not yet be implemented. When a group is marked aspirational, all tests within the group are taken to be aspirational as well. At this point, there is no particular processing for aspirational tests and groups, but we hope to implement it at some point in the future.

The =def-check= form is a deprecated synonym for =def-test=.

Package

nst.

Source

test-def.lisp.

Macro: def-test-generic (function-name &body forms) ¶

The =def-test-generic= declares a generic test function. #+begin_example
(def-test-generic FUNCTION-NAME)
#+end_example
For example,
#+begin_example
(nst:def-test-generic for-clses)
#+end_example

Package

nst.

Source

method.lisp.

Macro: def-test-group (group-name given-fixtures &body forms) ¶

The =def-test-group= form defines a group of the
given name, providing one instantiation of the bindings of the given fixtures
to each test. Groups can be associated with fixture sets, stateful
initialization, and stateful cleanup.
#+begin_example
(def-test-group NAME (FIXTURE FIXTURE ...)
(:aspirational FLAG)
(:setup FORM FORM ... FORM)
(:cleanup FORM FORM ... FORM)
(:startup FORM FORM ... FORM)
(:finish FORM FORM ... FORM)
(:each-setup FORM FORM ... FORM)
(:each-cleanup FORM FORM ... FORM)
(:include-groups GROUP GROUP ... GROUP)
(:documentation STRING)
TEST
...
TEST)
#+end_example
Arguments:
- group-name :: Name of the test group being defined
- given-fixtures :: List of the names of fixtures and anonymous fixtures to be used with the tests in this group.
- aspirational :: An aspirational test is one which verifies some part of an API or code contract which may not yet be implemented. When a group is marked aspirational, all tests within the group are taken to be aspirational as well. At this point, there is no particular processing for aspirational tests and groups, but we hope to implement it at some point in the future.
- forms :: Zero or more test forms, given by =def-check=.
- setup :: These forms are run once, before any of the individual tests, but after the fixture names are bound.
- cleanup :: These forms are run once, after all of the individual tests, but while the fixture names are still bound.
- startup :: These forms are run once, before any of the individual tests and before the fixture names are bound.
- finish :: These forms are run once, after all of the individual tests, and after the scope of the bindings to fixture names.
- each-setup :: These forms are run before each individual test.
- each-cleanup :: These forms are run after each individual test.
- include-group :: The test groups named in this form will be run (respectively reported) anytime this group is run (reported).
- documentation :: Docstring for the class.

Package

nst.

Source

group.lisp.

Macro: def-test-method (function-name (arg class) &body body) ¶

The =def-test-method= defines a general method for a generic test function. #+begin_example
(def-test-method FUNCTION-NAME (TEST-VALUE CLASS-NAME)
FORM
...
FORM)
#+end_example
- function-name :: The name of the test function for which we are defining a method.
- test-value :: Formal parameter to which the value under test will be bound. - class-name :: The class for which we are defining a method.
The method body should return a test result report, constructed with =make-success-result=, etc.
For example:
#+begin_example
(nst:def-test-method for-clses (o mid-cls)
(with-slots (mc1 mc2) o
(cond
((< mc1 mc2) (make-success-report))
(t (make-failure-report :format "~d not < ~d" :args (list mc1 mc2)))))) (nst:def-test-method for-clses (o side-cls)
(with-slots (sc1 sc2) o
(cond
((eql sc1 sc2) (make-success-report))
(t (make-failure-report :format "~d not eql ~d" :args (list sc1 sc2)))))) #+end_example

Package

nst.

Source

method.lisp.

Macro: def-test-method-criterion (function-name class documentation &optional criterion) ¶

The =def-test-method-criterion= macro provides a simple facility for defining a generic test function method in terms of an NST criterion. #+begin_example
(def-test-method-criterion FUNCTION-NAME CLASS-NAME [ CRITERION ] )
#+end_example
- function-name :: The name of the test function for which we are defining a
method.
- class-name :: The class for which we are defining a method.
- criterion :: The criterion to be applied to members of the class.
For example:
#+begin_example
(nst:def-test-method-criterion for-clses top-cls
(:predicate (lambda (tc) (< (tc1 tc) (tc2 tc)))))
#+end_example

Package

nst.

Source

method.lisp.

Macro: def-unary-negated-predicate-assert (assert-fn predicate default-message &rest keyargs &key message-defvar) ¶

Macro =def-unary-negated-predicate-assert= uses the negated result of a unary predicate as the basis of an assertion function. This macro’s arguments are just as for =def-unary-predicate-assert=.

Package

nst.

Source

process.lisp.

Macro: def-unary-predicate-assert (assert-fn predicate default-message &key message-defvar doc-state-flag pred-name &allow-other-keys) ¶

Macro =macro def-unary-predicate-assert= creates an assertion function using
the result of a call to a unary predicate. A non-nil result from the predicate
corresponds to a successful assertion.
#+begin_example
(def-unary-predicate-assert ASSERT-FN PREDICATE DEFAULT-MESSAGE
[ :message-defvar NAME ]
[ :pred-name NAME ]
[ :doc-state-flag BOOL ] )
#+end_example
- assert-fn :: The name of the assertion function being defined.
- predicate :: The predicate used to define the assertion function. It should take a single argument.
- default-message :: Format string used by default for reporting failures of this assertion. It should expect to be used in a call to =format= with one additional argument, the value being tested. - message-defvar :: The name of a global variable into which the default message will be stored. If this argument is omitted, the result of a call to =gensym= is used.
- pred-name :: This argument is used only for documenting the underlying predicate in the assertion function’s docstring. By default, it is the same as the predicate.

Package

nst.

Source

process.lisp.

Macro: def-values-criterion ((name args-formals forms-formals &key declare) &body forms) ¶

The =def-values-criterion= macro was deprecated as of NST 1.3.0. For new criteria, use =def-criterion= instead. In the short term, code using =def-values-criterion= should continue to work as before.

Package

nst.

Source

check.lisp.

Macro: emit-failure (&rest args) ¶

The =emit-failure= function is deprecated; use =make-failure-report= instead.

Package

nst.

Source

status.lisp.

Macro: emit-success (&rest args) ¶

The =emit-success= function is deprecated; use =make-success-report= instead.

Package

nst.

Source

status.lisp.

Macro: emit-warning (&rest args) ¶

The =emit-warning= function is deprecated; use =make-warning-report= instead.

Package

nst.

Source

status.lisp.

Macro: nst-cmd (&rest args) ¶

User-level NST operations are accessible from the REPL via the =nst-cmd= macro.
#+begin_example
(nst-cmd NST-COMMAND ARG ... ARG)
#+end_example
Where a particular system supports the facility (Currently Allegro, and SBCL under ACL-REPL) the top-level alias =:nst= provides a shorthand to this function.

Package

nst.

Source

command.lisp.

Macro: with-fixtures ((&rest fixtures) &body forms) ¶

The =with-fixtures= macro faciliates debugging and other non-NST uses of fixtures sets:
#+begin_example
(with-fixtures (FIXTURE FIXTURE ... FIXTURE)
FORM
FORM
...
FORM)
#+end_example
This macro evaluates the forms in a namespace expanded with the bindings provided by the fixtures.

Package

nst.

Source

fixture.lisp.

---

6.1.3 Ordinary functions

Function: add-error (result &key format args) ¶

For use within user-defined NST criteria: add an error to a result. #+begin_example
(add-error RESULT-REPORT [ :format FORMAT-STRING ] [ :args ARGUMENT-LIST ] ) #+end_example

Package

nst.

Source

status.lisp.

Function: add-failure (result &key format args) ¶

For use within user-defined NST criteria: add a failure to a result. #+begin_example
(add-failure RESULT-REPORT [ :format FORMAT-STRING ] [ :args ARGUMENT-LIST ]) #+end_example

Package

nst.

Source

status.lisp.

Function: add-info (result item) ¶

For use within user-defined NST criteria: add an info note to a result. #+begin_example
(add-info RESULT-REPORT INFO-ITEM)
#+end_example

Package

nst.

Source

status.lisp.

Function: assert-eq (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-EQ= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQ=, succeeds whenever that call returns non-nil.

Package

nst.

Source

process.lisp.

Function: assert-eql (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-EQL= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQL=, succeeds whenever that call returns non-nil.

Package

nst.

Source

process.lisp.

Function: assert-equal (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-EQUAL= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQUAL=, succeeds whenever that call returns non-nil.

Package

nst.

Source

process.lisp.

Function: assert-equalp (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-EQUALP= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQUALP=, succeeds whenever that call returns non-nil.

Package

nst.

Source

process.lisp.

Function: assert-non-nil (g0 &rest g1 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-NON-NIL= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It succeeds whenever the =NULL= function returns =nil=.

Package

nst.

Source

process.lisp.

Function: assert-not-eq (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-NOT-EQ= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQ=, succeeds whenever that call returns =nil=.

Package

nst.

Source

process.lisp.

Function: assert-not-eql (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-NOT-EQL= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQL=, succeeds whenever that call returns =nil=.

Package

nst.

Source

process.lisp.

Function: assert-not-equal (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-NOT-EQUAL= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQUAL=, succeeds whenever that call returns =nil=.

Package

nst.

Source

process.lisp.

Function: assert-not-equalp (g0 g1 &rest g2 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-NOT-EQUALP= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It compares the expected and tested values using =EQUALP=, succeeds whenever that call returns =nil=.

Package

nst.

Source

process.lisp.

Function: assert-null (g0 &rest g1 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-NULL= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It succeeds whenever the =NULL= function returns non-nil.

Package

nst.

Source

process.lisp.

Function: assert-zero (g0 &rest g1 &key format format-args fatal &allow-other-keys) ¶

The =ASSERT-ZERO= function is a unary predicate for use within the forms evaluated for an =:eval= criterion. It succeeds whenever the =ZEROP= function returns non-nil.

Package

nst.

Source

process.lisp.

Function: check-criterion-on-form (criterion form) ¶

This function verifies that the values return by evaluating the form adheres to the criterion.
#+begin_example
(check-criterion-on-form CRITERION FORM)
#+end_example

Package

nst.

Source

check.lisp.

Function: check-criterion-on-value (criterion val) ¶

The =check-criterion-on-value= function can be called from within a criterion body to verify that a value adheres to a criterion.
#+begin_example
(check-criterion-on-value CRITERION VALUE)
#+end_example

Package

nst.

Source

check.lisp.

Function: junit-results-by-group (&rest args &key verbose &allow-other-keys) ¶

The \texttt{junit-results-by-group} function writes the NST test results in JUnit XML format, organized by group, aligning test groups with Java classes, and individual tests with \texttt{@Test} methods. #+begin_example
(junit-results-by-group [ :verbose FLAG ]
[ :dir DIRECTORY ]
[ :file FILESPEC ]
[ :stream STREAM ]
[ :if-dir-does-not-exist BOOL ]
[ :if-file-exists BOOL ] )
#+end_example
Either =:dir= and =:file= options, or the =:stream= option, but not both, should
e used to specify the target for XML output; if none of the three options are
given, the function will write to =*standard-output*=.

Package

nst.

Source

junit.lisp.

Function: make-error-report (e &rest format-args) ¶

Function =make-error-report= produces a report of an error during test execution. #+begin_example
(make-error-report [ :format FORMAT-STRING ] [ :args ARG-FORM-LIST ] ) #+end_example

Package

nst.

Source

status.lisp.

Function: make-failure-report (&key format args info) ¶

The =make-failure-report= function returns a report of test failure. #+begin_example
(make-failure-report FORMAT ARGS)
#+end_example
The =format-string= and =args= are as to the Common Lisp function =format=. The =emit-failure= function is an older, deprecated version of this function.

Package

nst.

Source

status.lisp.

Function: make-success-report (&rest args &key warnings info skipped) ¶

The =make-success-report= function indicates a successful test result. #+begin_example
(make-success-report)
#+end_example
Note that some older examples show =(make-check-result)=, =(emit-success)= or =(check-result)=. The former is an internal function and should not be used from outside the core NST files. The latter two are deprecated.

Package

nst.

Source

status.lisp.

Function: make-warning-report (&key format args) ¶

Function =make-warning-report= is like =make-failure-report=, but provides supplimentary information as a warning.
#+begin_example
(make-warning-report [ :format FORMAT-STRING ] [ :args ARG-FORM-LIST ]) #+end_example
The =emit-warning= function is an older, deprecated version of this function.

Package

nst.

Source

status.lisp.

Function: wrap-thrown-lisp-warning (w) ¶

The helper function =wrap-thrown-lisp-warning= creates an NST =check-note= object from a standard Lisp =warning=.

Package

nst.

Source

status.lisp.

---

6.1.4 Generic functions

Generic Function: add-warning (result w &rest args) ¶

For use within user-defined NST criteria: add a warning to a
result.

The =add-warning= function adds an warning to a result record. The item can be any of a Lisp warning, an NST check-note or a format string; in the first two cases, no additional arguments should be provided.
#+begin_example
(add-warning RESULT-REPORT [ :format ITEM ] [ :args ARGUMENT-LIST ] ) #+end_example

Package

nst.

Source

status.lisp.

Methods

Method: add-warning (result (format-string string) &rest args) ¶

Method: add-warning (result (w check-note) &rest args) ¶

Method: add-warning (result (w warning) &rest args) ¶

Generic Function: arbitrary (typ) ¶

This function takes a single argument, which determines the
type of the value to be generated. For simple types, the name of the type (or the class object, such as returned by =find-class= by itself is a complete specification. For more complicated types, =arbitrary= can also take a list argument, where the first element gives the type and the remaining elements are keyword argument providing additional requirements for the generated value.

Package

nst.

Source

sampling.lisp.

Methods

Method: arbitrary ((spec cons)) ¶

Method: arbitrary (other) ¶

Generic Function: nst-junit-dump (stream) ¶

Function =nst-junit-dump= pushes the entire NST state to a JUnit XML file whose stream is specified by its argument.

Package

nst.

Source

junit.lisp.

Methods

Method: nst-junit-dump ((filename string)) ¶

Write the results of this session’s NST testing in JUnit XML format.

Method: nst-junit-dump ((stream stream)) ¶

---

6.1.5 Standalone methods

Writer Method: (setf class-name) ((method-context-layer method-context-layer)) ¶

automatically generated writer method

Source

method.lisp.

Target Slot

class-name.

Reader Method: class-name ((method-context-layer method-context-layer)) ¶

automatically generated reader method

Source

method.lisp.

Target Slot

class-name.

Method: initialize-instance :after ((p permuter) &key src &allow-other-keys) ¶

Source

permuter.lisp.

Method: print-object ((p permuter) stream) ¶

Source

permuter.lisp.

---

6.1.6 Method combinations

Method Combination: nst-results (&optional order) ¶

NST defines a method combination =nst-results= as the default
method combination for functions defined by =def-test-generic=. This combination runs /all/ applicable methods, and combines all of their results into a single NST result record.

This default can be overridden by specifying =t= as the method combination in the intial declaration.
#+begin_example
(nst:def-test-generic overridden (:method-combination t)) (nst:def-test-method-criterion overridden mid-cls
(:slots (mc1 (:eql 0))
(mc2 (:eql 2))))
(nst:def-test-method-criterion overridden bot-cls
(:slots (sc1 (:eql 1))
(sc2 (:eql 1))))

Package

nst.

Source

method.lisp.

Operator

check-result-union (function).

Identity with one argument

nil

---

6.2.1 Constants

Constant: +keyboard-interrupt-class+ ¶

Name of the class of error thrown when a keyboard interrupt is received, or nil if this implementation of Lisp has no such class.

Package

nst.

Source

interrupt.lisp.

---

6.2.2 Special variables

Special Variable: *char-escapes* ¶

Package

nst.

Source

junit.lisp.

Special Variable: *current-compound-structure-depth* ¶

Package

nst.

Source

sampling.lisp.

Special Variable: *default-character-range* ¶

Package

nst.

Source

sampling.lisp.

Special Variable: *default-debug-config* ¶

User variable: the default setting applied by default. Should be a list of alternating keyword/forms matching:
- nst-set - list of lists, each with arguments to :nst :set
- progn - list of forms to be evaluated

Package

nst.

Source

globals.lisp.

Special Variable: *default-debug-protect* ¶

Package

nst.

Source

globals.lisp.

Special Variable: *default-xml-pprint-dispatch* ¶

Package

nst.

Source

xml.lisp.

Special Variable: *entities* ¶

Package

nst.

Source

junit.lisp.

Special Variable: *fixture-bindings* ¶

Map implementing FIXTURE-BINDINGS: from fixture name to the list of local variable names bound that fixture

Package

nst.

Source

fixture.lisp.

Special Variable: *fixture-letlist* ¶

Map implementing FIXTURE-LETLIST: from fixture name to the list of local variable names bound that fixture

Package

nst.

Source

fixture.lisp.

Special Variable: *fixture-record* ¶

Map implementing FIXTURE-RECORD: from fixture name to its =fixture-record=

Package

nst.

Source

fixture.lisp.

Special Variable: *generate-backtraces* ¶

User variable: if non-null, will attempt to capture the Lisp backtrace of errors in tests.

Package

nst.

Source

globals.lisp.

Special Variable: *group-records* ¶

Primary storage of group and test records; this level of map translates from group name to an instance of =group-record=.

Package

nst.

Source

group.lisp.

Special Variable: *implicit-group-choice* ¶

Package

nst.

Source

runner.lisp.

Special Variable: *last-repl-call* ¶

Package

nst.

Source

command.lisp.

Special Variable: *max-auto-array-rank* ¶

Package

nst.

Source

sampling.lisp.

Special Variable: *nst-check-internal-name* ¶

Dynamic variable used to set the name of a test in its result report.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-check-user-name* ¶

Dynamic variable used to set the name of a test in its result report.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-context* ¶

Dynamic-scoped variable recording the values under test - a list of context-layer instances.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-context-evaluable* ¶

Dynamic-scoped variable tracking whether the values under test should be asusmed evaluated. Used in preparing context expressions.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-debug* ¶

User variable: apply customizable debugging settings.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-group-name* ¶

Dynamic variable used to set the name of the group in a test result report.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-group-shown* ¶

Dynamic-scoped variable tracking whether the name of a group has been printed, so that tests need not repeat it.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-report-driver* ¶

Dynamic-scoped variable - one of :multiple, :package, :group or :test to determine the top-level form of a report. Used as a control parameter for printing reports.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-stack* ¶

Dynamic-scoped variable - the stack of values under test by the current criterion.

Package

nst.

Source

globals.lisp.

Special Variable: *nst-verbosity* ¶

User variable determining how verbose NST’s output to the REPL should be. Internally, this variable takes an integer value: 0 and below are silent, 1 is the default, 2 and 3 are more verbose, and 4 is for full tracing. The command-line interpreter assigns keywords to these values, from most terse to most verbose: :silent, nil, :quiet, :default, t, :verbose, :vverbose (:quiet and :default are the same, and are the initial setting).

Package

nst.

Source

globals.lisp.

Special Variable: *test-methods* ¶

Global variable for programmer-defined NST test methods.

Package

nst.

Source

method.lisp.

Special Variable: +arbitrary-generable-types+ ¶

Package

nst.

Source

sampling.lisp.

Special Variable: +name-uses+ ¶

Map from a symbol in the =:nst-name-usage= package to a =name-use= instance decribing how a symbol of the same name is used for NST artifacts.

Package

nst.

Source

artifacts.lisp.

Special Variable: +nst-repl-commands+ ¶

Package

nst.

Source

command.lisp.

Special Variable: +nst-repl-properties+ ¶

Package

nst.

Source

command.lisp.

Special Variable: +results-record+ ¶

Results of test runs.

Package

nst.

Source

artifacts.lisp.

Special Variable: +scalar-generable-types+ ¶

Package

nst.

Source

sampling.lisp.

Special Variable: qw ¶

Package

nst.

Source

permuter.lisp.

Special Variable: qwerty ¶

Package

nst.

Source

permuter.lisp.

---