diff --git a/docs/implementing-tests.md b/docs/implementing-tests.md new file mode 100644 index 000000000..09137ef99 --- /dev/null +++ b/docs/implementing-tests.md @@ -0,0 +1,72 @@ +# Implementing Tests in Coalton + +Letting Coalton run loose in a Fiasco test suite can cause a bit of havoc, but, with a little finesse, Coalton and Fiasco can interact safely and smoothly. + +## An Example Coalton Package: +``` +(defpackage #:foobar + (:use #:coalton + #:coalton-prelude) + (:export #:add-twenty + #:baz-it)) + +(in-package #:foobar) + +(coalton-toplevel + (define (add-twenty x) + (+ x 20)) + + (define (baz-it string) + (coalton-library/string:concat "baz-" string))) +``` +## Defining the test package + +When defining a test package for a Coalton project, you'll actually make two separate packages, one for native Coalton tests, and another that will alias your Coalton tests into a Fiasco test package (in addition to any Common Lisp specific tests you want to implement). + +### First you will define the Fiasco test package for your project: +``` +(fiasco:define-test-package #:foobar-tests + (:use #:cl)) + +``` +### Then, you will write a separate package for handling tests written in Coalton: + +Note: In order to use #:coalton-testing, either run `(ql:quickload :coalton/testing)` or add `#:coalton/testing` to your project's .asd file. +``` +(defpackage #:foobar-native-tests + (:use #:coalton-testing #:foobar)) +``` +### Next, you will initialize Fiasco within your Coalton test-package: +``` +(in-package #:foobar-native-tests) + +(coalton-fiasco-init #:foobar-tests) +``` + +### From there, you're all set to write your test suite: + +``` +(in-package #:foobar-native-tests) + +(define-test foobarbaz-tests () + (is (== (add-twenty 1) 21)) + (is (== (foobar::baz-it "squatch") "baz-squatch"))) +``` +## Running the test suite +Just like with any Fiasco test suite, you can run your tests from the REPL. + +Make sure you're in the Common Lisp/Fiasco test package for your project (in this case `#:foobar-tests`), and then run `(run-package-tests)`: +``` +FOOBAR> (in-package #:foobar-tests) +# +FOOBAR-TESTS> (run-package-tests) +FOOBAR-TESTS (Suite) + FOOBARBAZ-TESTS.........................................................[ OK ] + +T +(#) +; processing (COALTON-TOPLEVEL (DEFINE # ...) ...) +; processing (DEFINE-TEST FOOBARBAZ-TESTS ...) +``` + +## Congratulations! You have a working Coalton test suite! \ No newline at end of file