Feature Request: Tutorial on using 1am

[jgarte]

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:

(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)

[jgarte]

phoe had mentioned on matrix how he decides on a test framework.

I think that this advice might be useful for beginners trying to decide on how to test CL code as well:

my two eurocents in the topic; how dumb is the code I am testing?

the code is dumber than me - DEFUN over ASSERT
the code is dumber than average and also tiny - 1am
the code is of average or higher non-dumbness, or there's more than one page of it - parachute

[vindarel]

mmmh but we have a good tutorial for a good and popular testing framework (5am), so not sure a review of 1am would fit in the Cookbook.

I'll add a "wontfix" tag, but happy to see more discussion.

[jgarte]

Hi @vindarel

As I mentioned in the example above, phoe uses a particular testing framework based on the following criteria:

... how dumb is the code I am testing?

the code is dumber than me - DEFUN over ASSERT
the code is dumber than average and also tiny - 1am
the code is of average or higher non-dumbness, or there's more than one page of it - parachute

5am seems to fit into the category of "the code is of average or higher non-dumbness ..." although I can see it used in simpler settings.

But in the spirit of quick recipes, "DEFUN over ASSERT" might be the most elegant solution, especially for a beginner where 5am would be overkill for their purposes.

I agree with the philosophy here of using the right testing tool for the job.

In other words, I'm not sure if 5am is the "correct hammer" for every job, especially a simple one.

Should the advice we give for testing practices with CL transcend the use of any particular library and instead think about what it is that we are trying to achieve when testing? The library recommendation, following from the testing practices. I can see how this can easily be a book though and maybe fall out of scope for a cookbook. That said, I think it would be beneficial to bear this in mind even in the cookbook context, adjusting accordingly.

mmmh but we have a good tutorial for a good and popular testing framework (5am), so not sure a review of 1am would fit in the Cookbook.

Is this because you'd like the cookbook to show just one way of doing things?

If so, do you think that we should state a project goal in the README that we should not duplicate concepts to show different approaches taken as it is out of scope for the project? I realize that this would then make the cookbook more opinionated towards doing things but maybe that is a given.

[vindarel]

Good point in that talking about 5AM up front on the testing page is quite much. Now I think it'd great if we introduced simpler testing patterns -the opportunity to teach some CL.

Random thoughts on 1am: you can write a tutorial outside the Coobook to educate us all ;) It has no Github activity and even if it's done© this gives a very bad image of CL to newcomers; 5AM has some plugins; 1AM doesn't mention fixtures, something I judge basic for a test framework; Phoe is an experienced lisper and experienced lispers can form other opinions after they have learned the basics and the popular tools!

[jgarte]

Now I think it'd great if we introduced simpler testing patterns -the opportunity to teach some CL.

What simpler testing patterns were you thinking of more or less?

Random thoughts on 1am: you can write a tutorial outside the Coobook to educate us all ;)

Thanks for the idea. I'll have to educate my self a bit more on 1AM first and then I'll be able to write that tutorial ;()

I'll let you know once it is published.

[vindarel]

What simpler testing patterns were you thinking of more or less?

First, assert as you said, also the #+my-test trick, using closures, unwind-protect, recalling the interactive debugger features, maybe a simple macro.