2025-05-12 test-doc-blocks | Clojure Slack Archive

test-doc-blocks 2025-05-12

Matti Uusitalo 2025-05-12T13:12:08.289279Z

@matti.uusitalo117 has joined the channel

Matti Uusitalo 2025-05-12T13:15:17.943509Z

Hello! Trying to use this and ran into some trouble. How would one write a multi line assertion, the kind that is useful for bigger data structures? For example:

(m/ast non-empty-string)
;; => {:type :string
;;     :properties {:min 1}}

This ends up throwing. Same happens with

(m/ast non-empty-string)
;; => {:type :string
;     :properties {:min 1}}

I was also looking at the sample from https://github.com/lread/test-doc-blocks/blob/main/doc/example.md#indented-blocks which made me try

(m/ast non-empty-string)
;; => 
; {:type :string
;  :properties {:min 1}}

but that emits

(m/ast non-empty-string)
=> 
; {:type :string
;     :properties {:min 1}}

which doesn't work

lread 2025-05-12T13:46:49.004789Z

Hi @matti.uusitalo117! I wrote and use test-doc-blocks, but am rusty on the details of what it supports here. I'll take a peek.

lread 2025-05-12T14:28:12.512829Z

Huh! Yes, I see your point:

# README

clojure ;; this works (map inc [1 2 3 4 5 6]) => [2 3 4 5 6 7]

clojure ;; this works... (map inc [1 2 3 4 5 6]) ;; => [2 3 4 5 6 7]

clojure ;; this fails at test generation time with Unexpected EOF (map inc [1 2 3 4 5 6]) ;; => [2 3 ;; 4 5 ;; 6 7]

🙌 1

lread 2025-05-12T14:54:29.145499Z

Raised an issue: https://github.com/lread/test-doc-blocks/issues/33

Matti Uusitalo 2025-05-14T09:38:22.961979Z

I didn't fully understand why the single semicolon was needed. Hopefully this latest change doesn't break existing use cases.

Matti Uusitalo 2025-05-14T09:40:11.055399Z

At least I don't see any difference between these examples

(=
   (prep-block-for-conversion-to-test ";; =stdout=> line1
; line2")

   (prep-block-for-conversion-to-test ";; =stdout=> line1
;; line2"))
;; => true

lread 2025-05-14T11:02:33.018119Z

iirc, I think the single semicolon for stdout and stderr allowed us to know when those blocks ended.

(somefn)
;; =sdtout=> 
; out1
; out2
; =sdtderr=> out3
;; =stderr=>
; err1
; err2
; => err3
;; => eval-result

That make sense? Eval out is more structured so might not need this distinction.

Matti Uusitalo 2025-05-14T11:04:10.593809Z

I see, so the difference wouldn't be noticeable in my little example

Matti Uusitalo 2025-05-14T11:14:35.282589Z

This seems to work fine

clojure (def multi-arity-pow (m/-instrument {:schema [:function [:=> [:cat :int] [:int {:max 6}]] [:=> [:cat :int :int] [:int {:max 6}]]] :scope #{:input :output} :report println} (fn ([x] (* x x)) ([x y] (* x y))))) (multi-arity-pow 4) ;; =stdout=> :malli.core/invalid-output {:output [:int {:max 6}], :value 16, :args [4], :schema [:=> [:cat :int] [:int {:max 6}]]} ;; => 16 (multi-arity-pow 5 0.1) ;; =stdout=> :malli.core/invalid-input {:input [:cat :int :int], :args [5 0.1], :schema [:=> [:cat :int :int] [:int {:max 6}]]} ;; :malli.core/invalid-output {:output [:int {:max 6}], :value 0.5, :args [5 0.1], :schema [:=> [:cat :int :int] [:int {:max 6}]]} ;; => 0.5

It yields sensible tests too!

Matti Uusitalo 2025-05-14T11:37:05.994169Z

I've been able to use this to test the majority of examples in metosin/malli's markdown documentation

Matti Uusitalo 2025-05-14T11:37:50.228069Z

The limitations are not due to test-doc-blocks

lread 2025-05-14T11:44:23.820279Z

still traveling… happy to take a deeper peek when I get back

🙌 1

Matti Uusitalo 2025-05-13T08:49:20.668149Z

Thanks for showing a working example. I can work with this. Great library!

Matti Uusitalo 2025-05-13T11:31:35.413679Z

This seems to work: https://github.com/lread/test-doc-blocks/pull/35

Matti Uusitalo 2025-05-13T11:32:41.204259Z

It would allow both the old style without leading comments and the one that is consistent with =stdout=> style

lread 2025-05-13T11:41:23.665559Z

Oh thanks, @matti.uusitalo117! I'm travelling today and tomorrow, and will take a look as soon as I can.

Matti Uusitalo 2025-05-13T11:41:45.889859Z

All good. 🫡

Matti Uusitalo 2025-05-13T11:45:02.773289Z

In the meantime I'll try to test this further to see if there's hiccups

lread 2025-05-13T11:47:36.886949Z

Cool. One thing I was wondering was if we actually technically needed the subsequent lines to start with a single ; or would it also be ok for it to start with ;;. I think the latter should be ok too (and more user-friendly), but haven't thought it through yet.

Matti Uusitalo 2025-05-13T11:48:52.753959Z

Yeah. I had a homegrown stub of a tool like this that worked like that, but since learning about this tool I'd much prefer to use this. The solutions how to add metadata to the blocks and support for different engines is great

lread 2025-05-13T11:50:11.925869Z

Glad you are enjoying it.

Matti Uusitalo 2025-05-13T11:53:49.598819Z

Now that you mention it, it would be way less error prone if the leading comments can be one-or-more semicolons

lread 2025-05-13T11:58:18.028589Z

Yeah there was a good reason for =stdout=> continuation to use the single semicolon... but this continuation... might be ok with multiple semicolons... unless we realize it's not ok. simple_smile

Matti Uusitalo 2025-05-14T05:20:32.615619Z

Added some unit tests. Also the latest commit has support for using multiple semicolons. Appears to be just a small adjustment to the regex in body_prep

Matti Uusitalo 2025-05-15T11:01:05.162719Z

I added some tests for md and adoc for this feature as well

Clojurians Log v2

test-doc-blocks 2025-05-12