LispCookbook / LispCookbook/cl-cookbook

Feature Request: Tutorial on using 1am (or simpler testing patterns)

Open
#476 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

wontfix
Dominant language
JavaScript
Stars
1.1k
Forks
158
Avg merge
6d 3h
Merged PRs (30d)
2

Description

[1am](https://github.com/lmj/1am) is a classic CL testing framework that fits on a page.

`1am` is also a good testing framework for beginners because it is easy to learn for small projects.

I'd like to see a tutorial using it.

Here are some draft ideas for relevant content from my notes in discussion with [phoe](https://phoe.github.io/):

```lisp
(ql:quickload :1am)
(ql:quickload :alexandria)

(add-package-local-nickname :a :alexandria)

(defun my-length (l)
"Takes the length of a list or vector."
(etypecase l
(list (list-length l))
(vector (array-dimension l 0))))

(defun test-my-length ()
"Testing my-length with 1am."
(1am:is (= 12 (my-length (a:iota 12))))
(1am:is (= 12 (my-length (coerce (a:iota 12) 'vector))))

;; Check that passing a keyword signals an error.
(1am:signals type-error (= :hahaha (my-length (coerce (a:iota 12) 'vector))))
(1am:signals type-error (= :hahaha (my-length (a:iota 12)))))

(test-my-length)
```

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the issue's draft Common Lisp example and the linked 1am project, then run the supplied Quicklisp setup and tests. Done means a tutorial explains beginner testing with 1am, including the my-length examples and error checks, in a form suitable for the cookbook.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, testing
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.