gleam
gleam copied to clipboard
gleam-lang
Provide option for running/checking doctests
As requested by Louis in gleam-lang/stdlib#226
We have a convention of creating doc-test like lines in the documentation comments for types & functions but we don't have a way for the compiler/build-system/test-setup to check their validity.
The linked PR includes a node script that attempts to find doc-test like entries and make an individually numbered test for each one and in per-module test files in the tests folder so that they can be run by the standard tests mechanism. It would be good to have something like that (or better) built into the language tooling.
Louis, should that happen by examining the AST for documentation comments and then generating AST for the test files? I guess the test have to be generated into files as we have no way to execute them in memory at the moment right?
Would there but a gleam build doc-tests for something? What UX to you feel should exist?
A great suggestion! Something we want for sure.
Louis, should that happen by examining the AST for documentation comments and then generating AST for the test files? I guess the test have to be generated into files as we have no way to execute them in memory at the moment right?
Yes you're right. I think this would work by during compilation parsing the doc comments to extract Gleam fenced code blocks and inserting them into test modules. We could do this when the --test flag is given to the compile-package command as we know that we are also compiling tests in this situation.
Exactly what code is to be generated I am unsure. There is a larger question of how testing should work in Gleam. One thing I have been considering is adding a test keyword for tests, giving us a way to do some test discovery and to also enable embedding tests in application modules.
test does_the_thing {
assert thingy() == Ok(1)
}
When you say 'Gleam fenced code blocks' and you're looking to move away from the 4 space indentation?
/// Rounds the value to the nearest whole number as an int.
///
/// ## Examples
///
/// > round(2.3)
/// 2
///
/// > round(2.5)
/// 3
///
pub fn round(float: Float) -> Int {
do_round(float)
}
to something like:
/// Rounds the value to the nearest whole number as an int.
///
/// ## Examples
///
/// ```
/// > round(2.3)
/// 2
/// ```
/// ```
/// > round(2.5)
/// 3
/// ```
///
pub fn round(float: Float) -> Int {
do_round(float)
}
I guess it might be useful to have something that separates compilable testable doc-tests from just example code. Maybe:
/// ```test
/// > round(2.5)
/// 3
/// ```
If you're embracing code fences.
I also think it might be useful to have markup that says "these lines of code are required for this thing to compile and run but I don't necessary want to show them in the example in the docs". I'm not sure though.
Yes I think I would like to use the triple backtick syntax as the indentation one can be a little confusing given the extra space at the start.
I also think it might be useful to have markup that says "these lines of code are required for this thing to compile and run but I don't necessary want to show them in the example in the docs". I'm not sure though.
That's a fab idea. I think Rust has something for this, perhaps we can copy them.
Taking a look at the doc tooling might be my next contribution to gleam itself. I don't wanna say I'll get to this right away, but I'd like to look at it soon :)
