Doc on how to write a Coalton test suite

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)
+#<PACKAGE "FOOBAR-TESTS">
+FOOBAR-TESTS> (run-package-tests)
+FOOBAR-TESTS (Suite)
+  FOOBARBAZ-TESTS.........................................................[ OK ]
+
+T
+(#<test-run of FOOBAR-TESTS: 2 tests, 2 assertions, 0 failures in 8.3e-5 sec>)
+; processing (COALTON-TOPLEVEL (DEFINE # ...) ...)
+; processing (DEFINE-TEST FOOBARBAZ-TESTS ...)
+```
+
+## Congratulations! You have a working Coalton test suite!