Write test timeout article

Author: GearsDatapacks

blog/gleam-test-timeouts.djot

@@ -0,0 +1,147 @@
+---
+title = "Test timeouts in Gleam"
+date = "2025-11-25"
+description = "By default, Gleam tests come with a timeout of 5 seconds. It's not as easy as you might think to remove it."
+---
+
+If you don't care about the backstory and just want to know the answer, you can
+[skip there](#How-do-I-configure-my-test-timeout).
+
+## How Gleam tests work
+
+When you create a new Gleam project, there are two dependencies that are added
+automatically by the build tool. These are [`gleam_stdlib`](https://hexdocs.pm/gleam_stdlib),
+the Gleam standard library, and [`gleeunit`](https://hexdocs.pm/gleeunit), the
+default test runner for Gleam.
+
+Both of these dependencies are technically optional, but they are added by default
+to make it easier to start a new project, since most projects use both the above
+packages.
+
+See, when you run `gleam test` in the terminal, while it may seem that the Gleam
+build tool finds all your test functions magically, all it's really doing is calling
+the `main` function of the module named `$PROJECT_test`, which by default calls
+out to `gleeunit`, which is the code that's really in charge of running your tests.
+
+## What is gleeunit?
+
+On the Erlang target, the `gleeunit` library is a thin wrapper for
+[`EUnit`](https://www.erlang.org/doc/apps/eunit/chapter.html), which is a test
+runner built into OTP. On JavaScript, `gleeunit` implements a custom test runner
+that has similar (but not identical) features to `EUnit`.
+
+Somewhat unfortunately, EUnit comes with a default timeout of 5 seconds, and
+seemingly [no way to globally adjust it](https://github.com/lpil/gleeunit/issues/51)
+so if any test runs for longer than that it is immediately terminated.
+
+EUnit has a somewhat unconventional API. As the default Gleam project explains,
+it runs all public functions whose names end in `_test`. But there's a second
+more obscure API, in the form of *test generators*.
+
+Test generators are another kind of EUnit test. Test generator functions end
+in `*_test_` (note the trailing underscore), and they have the ability to configure
+various parts of how EUnit runs. It's detailed in the EUnit documentation,
+but here we will just cover the most commonly used one, which is the timeout.
+
+## How do I configure my test timeout?
+
+EUnit test generators allow returning extra values along with a function to call
+in order to configure it. In Erlang syntax, here is how you would configure the
+timeout for your test, to be 60 seconds instead of 5:
+
+```erlang
+something_test_() ->
+  {timeout, 60, fun () -> 
+    ... % The actual body of your test 
+  }.
+```
+
+So, what does this translate to Gleam? Well, there are actually two ways to do it.
+The first is to use the `atom.create` function from the [`gleam_erlang`](https://hexdocs.pm/gleam_erlang)
+library. This creates basically the same as the Erlang code:
+
+```gleam
+import gleam/erlang/atom
+
+pub fn something_test_() {
+  #(atom.create("timeout"), 60, fn() {
+    ... // The actual body of your test
+  })
+}
+```
+
+This works, but it has a couple of drawbacks. Firstly, you need to pull in a new
+library just to create this one atom, and secondly it just doesn't look very nice.
+My preferred solution takes advantage of the way that custom types are represented
+in Gleam.
+
+When Gleam compiles to Erlang, Gleam custom types become an Erlang tuple tagged
+with an atom. So the Gleam value `Ok(10)` becomes the Erlang `{ok, 10}`. This is
+perfect for what we need, because it's the exact same format as what EUnit expects.
+Using that knowledge we can define a custom type to represent the timeout tuple:
+
+```gleam
+pub type Timeout(a) {
+  Timeout(time: Int, function: fn() -> a)
+}
+```
+
+You can use `Float` instead for `time` here, but I find I rarely need to set my
+timeout to a fraction of a second, so `Int` is more convenient. Now, we can take
+advantage of Gleam's [`use` syntax](https://tour.gleam.run/advanced-features/use/),
+which allows us to turn a call to a higher order function — where we pass an anonymous
+function, like we did in the previous example — into a flattened statement.
+We now get a much nicer looking test:
+
+```gleam
+pub type Timeout(a) {
+  Timeout(time: Int, function: fn() -> a)
+}
+
+pub fn something_test_() {
+  use <- Timeout(60)
+  ... // The actual body of your test
+}
+```
+
+Great! We've successfully worked around EUnit's annoying timeout. Job done! But
+wait...
+
+## Multi-target tests
+
+Remember when I mentioned earlier about how `gleeunit` works differently on the
+JavaScript target? Well, the good news is that it doesn't have a timeout like on
+the Erlang target, but the bad news is that it doesn't support test generators.
+So if all your tests are called `*_test_`, none of them are going to run on
+the JavaScript target.
+
+The only real way to get around this is to write a bit of extra boilerplate for
+all of your tests. You need to write a test that runs only on JavaScript, that
+calls the same code as the Erlang test. There's only really one way achieve this,
+with the `@target` attribute, and it's not pretty. Here's an example:
+
+```gleam
+// This runs on Erlang
+pub fn something_test_() {
+  use <- Timeout(60)
+  ... // The actual body of your test
+}
+
+// This runs on JavaScript
+@target(javascript)
+pub fn something_test() {
+  something_test_().function()
+}
+```
+
+The `@target` attribute is deprecated, and you shouldn't use it really, but there
+isn't any alternative for this specific case. Hopefully soon we will have an
+alternative, both to `@target`, and to this problem of different behaviour in the
+test runner across targets.
+
+## Conclusion
+
+If you want to change the timeout of a test that only runs on Erlang, it's not
+very hard. If you want to have tests that run on both targets for longer than 5
+seconds, it gets messy.
+Hopefully there will be a better way to do it in the near future.

blog/test.djot

@@ -19,6 +19,9 @@ lustre = ">= 5.0.2 and < 6.0.0"
 tom = ">= 1.1.0 and < 2.0.0"
 simplifile = ">= 2.2.0 and < 3.0.0"
 lustre_ssg = ">= 0.11.0 and < 1.0.0"
+jot = ">= 4.0.0 and < 5.0.0"
+pearl = ">= 2.2.0 and < 3.0.0"
+contour = ">= 1.2.1 and < 2.0.0"
 
 [dev-dependencies]
 gleeunit = ">= 1.0.0 and < 2.0.0"

gleam.toml

@@ -2,30 +2,38 @@
 # You typically do not need to edit this file
 
 packages = [
+  { name = "contour", version = "1.2.1", build_tools = ["gleam"], requirements = ["gleam_community_ansi", "gleam_stdlib", "glexer", "houdini"], otp_app = "contour", source = "hex", outer_checksum = "C7895472BBAAC5D15DBDBAF6DD1847F6981F2F6132F726BAD30434A6E3BAAB95" },
   { name = "envoy", version = "1.0.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "envoy", source = "hex", outer_checksum = "95FD059345AA982E89A0B6E2A3BF1CF43E17A7048DCD85B5B65D3B9E4E39D359" },
   { name = "exception", version = "2.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "exception", source = "hex", outer_checksum = "329D269D5C2A314F7364BD2711372B6F2C58FA6F39981572E5CA68624D291F8C" },
   { name = "filepath", version = "1.1.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "B06A9AF0BF10E51401D64B98E4B627F1D2E48C154967DA7AF4D0914780A6D40A" },
+  { name = "gleam_community_ansi", version = "1.4.3", build_tools = ["gleam"], requirements = ["gleam_community_colour", "gleam_regexp", "gleam_stdlib"], otp_app = "gleam_community_ansi", source = "hex", outer_checksum = "8A62AE9CC6EA65BEA630D95016D6C07E4F9973565FA3D0DE68DC4200D8E0DD27" },
+  { name = "gleam_community_colour", version = "2.0.2", build_tools = ["gleam"], requirements = ["gleam_json", "gleam_stdlib"], otp_app = "gleam_community_colour", source = "hex", outer_checksum = "E34DD2C896AC3792151EDA939DA435FF3B69922F33415ED3C4406C932FBE9634" },
   { name = "gleam_crypto", version = "1.5.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_crypto", source = "hex", outer_checksum = "50774BAFFF1144E7872814C566C5D653D83A3EBF23ACC3156B757A1B6819086E" },
   { name = "gleam_erlang", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "1124AD3AA21143E5AF0FC5CF3D9529F6DB8CA03E43A55711B60B6B7B3874375C" },
   { name = "gleam_json", version = "3.0.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_json", source = "hex", outer_checksum = "874FA3C3BB6E22DD2BB111966BD40B3759E9094E05257899A7C08F5DE77EC049" },
   { name = "gleam_otp", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "gleam_otp", source = "hex", outer_checksum = "BA6A294E295E428EC1562DC1C11EA7530DCB981E8359134BEABC8493B7B2258E" },
   { name = "gleam_regexp", version = "1.1.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_regexp", source = "hex", outer_checksum = "9C215C6CA84A5B35BB934A9B61A9A306EC743153BE2B0425A0D032E477B062A9" },
   { name = "gleam_stdlib", version = "0.65.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "7C69C71D8C493AE11A5184828A77110EB05A7786EBF8B25B36A72F879C3EE107" },
   { name = "gleeunit", version = "1.6.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "FDC68A8C492B1E9B429249062CD9BAC9B5538C6FBF584817205D0998C42E1DAC" },
+  { name = "glexer", version = "2.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "splitter"], otp_app = "glexer", source = "hex", outer_checksum = "40A1FB0919FA080AD6C5809B4C7DBA545841CAAC8168FACDFA0B0667C22475CC" },
   { name = "houdini", version = "1.2.0", build_tools = ["gleam"], requirements = [], otp_app = "houdini", source = "hex", outer_checksum = "5DB1053F1AF828049C2B206D4403C18970ABEF5C18671CA3C2D2ED0DD64F6385" },
   { name = "jot", version = "4.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "houdini", "splitter"], otp_app = "jot", source = "hex", outer_checksum = "E9E266D2768EA1238283D2CF125AA68095F17BAA4DDF3598360FD19F38593C59" },
   { name = "lustre", version = "5.3.5", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_json", "gleam_otp", "gleam_stdlib", "houdini"], otp_app = "lustre", source = "hex", outer_checksum = "5CBB5DD2849D8316A2101792FC35AEB58CE4B151451044A9C2A2A70A2F7FCEB8" },
   { name = "lustre_ssg", version = "0.11.0", build_tools = ["gleam"], requirements = ["filepath", "gleam_regexp", "gleam_stdlib", "jot", "lustre", "simplifile", "temporary", "tom"], otp_app = "lustre_ssg", source = "hex", outer_checksum = "D1F2B47EBE27C2B1DE6552A0883BC676D8EB076359D152FFA323FADDC74FFC41" },
+  { name = "pearl", version = "2.2.0", build_tools = ["gleam"], requirements = ["gleam_community_ansi", "gleam_stdlib", "houdini", "splitter"], otp_app = "pearl", source = "hex", outer_checksum = "E5E14CE725542BA2516570D04140F0D1471761CCE27C6579C6396369FFF1DA9F" },
   { name = "simplifile", version = "2.3.0", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "0A868DAC6063D9E983477981839810DC2E553285AB4588B87E3E9C96A7FB4CB4" },
   { name = "splitter", version = "1.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "splitter", source = "hex", outer_checksum = "05564A381580395DCDEFF4F88A64B021E8DAFA6540AE99B4623962F52976AA9D" },
   { name = "temporary", version = "1.0.0", build_tools = ["gleam"], requirements = ["envoy", "exception", "filepath", "gleam_crypto", "gleam_stdlib", "simplifile"], otp_app = "temporary", source = "hex", outer_checksum = "51C0FEF4D72CE7CA507BD188B21C1F00695B3D5B09D7DFE38240BFD3A8E1E9B3" },
   { name = "tom", version = "1.1.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "tom", source = "hex", outer_checksum = "0910EE688A713994515ACAF1F486A4F05752E585B9E3209D8F35A85B234C2719" },
 ]
 
 [requirements]
+contour = { version = ">= 1.2.1 and < 2.0.0" }
 gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
 gleeunit = { version = ">= 1.0.0 and < 2.0.0" }
+jot = { version = ">= 4.0.0 and < 5.0.0" }
 lustre = { version = ">= 5.0.2 and < 6.0.0" }
 lustre_ssg = { version = ">= 0.11.0 and < 1.0.0" }
+pearl = { version = ">= 2.2.0 and < 3.0.0" }
 simplifile = { version = ">= 2.2.0 and < 3.0.0" }
 tom = { version = ">= 1.1.0 and < 2.0.0" }

manifest.toml

@@ -60,9 +60,7 @@ pub fn text_page(header: String, content: List(Element(a))) -> Section(a) {
         [html.text(header)],
       ),
     ]),
-    html.div([attribute.class("mx-auto max-w-4xl py-8 leading-8")], [
-      html.p([attribute.class("text-xl")], content),
-    ]),
+    html.div([attribute.class("mx-auto max-w-4xl py-8 leading-8")], content),
   ])
 }
 

src/website/component.gleam

@@ -1,11 +1,18 @@
+import contour
 import gleam/bool
 import gleam/dict.{type Dict}
 import gleam/list
+import gleam/option
 import gleam/string
+import jot
+import lustre/attribute.{attribute}
 import lustre/element
+import lustre/element/html
 import lustre/ssg/djot
+import pearl
 import simplifile
 import tom.{type Toml}
+import website/component
 
 pub fn posts() -> List(Post(a)) {
   let assert Ok(files) = simplifile.read_directory("blog/")
@@ -16,7 +23,7 @@ pub fn posts() -> List(Post(a)) {
     let assert Ok(contents) = simplifile.read(file_path)
 
     let assert Ok(metadata) = djot.metadata(contents)
-    let contents = djot.render(contents, djot.default_renderer())
+    let contents = djot.render(contents, renderer())
 
     let title = get_string_key(metadata, "title")
     let description = get_string_key(metadata, "description")
@@ -28,6 +35,71 @@ pub fn posts() -> List(Post(a)) {
   })
 }
 
+fn renderer() -> djot.Renderer(element.Element(a)) {
+  let default = djot.default_renderer()
+  djot.Renderer(
+    ..default,
+    link: fn(destination, references, content) {
+      case destination {
+        jot.Reference(ref) ->
+          case dict.get(references, ref) {
+            Ok(url) ->
+              html.a(
+                [
+                  attribute.href(url),
+                  attribute.target(target(url)),
+                  attribute.class("underline"),
+                ],
+                content,
+              )
+            Error(_) ->
+              html.a(
+                [
+                  attribute.href("#" <> ref),
+                  attribute.id("back-to-" <> ref),
+                ],
+                content,
+              )
+          }
+        jot.Url(url) ->
+          html.a(
+            [
+              attribute.href(url),
+              attribute.target(target(url)),
+              attribute.class("underline"),
+            ],
+            content,
+          )
+      }
+    },
+    codeblock: fn(attrs, lang, code) {
+      let lang = option.unwrap(lang, "text")
+
+      let code = case lang {
+        "erlang" | "erl" -> component.dangerous_html(pearl.highlight_html(code))
+        "gleam" -> component.dangerous_html(contour.to_html(code))
+        _ -> html.text(code)
+      }
+
+      html.pre(
+        dict.fold(attrs, [], fn(attrs, name, value) {
+          [attribute(name, value), ..attrs]
+        }),
+        [
+          html.code([attribute("data-lang", lang)], [code]),
+        ],
+      )
+    },
+  )
+}
+
+fn target(url: String) -> String {
+  case url {
+    "https://" <> _ | "http://" <> _ -> "_blank"
+    _ -> ""
+  }
+}
+
 fn get_string_key(toml: Dict(String, Toml), key: String) -> String {
   let assert Ok(value) = dict.get(toml, key)
   let assert tom.String(value) = value