# [Writing jldoctests](@id writing-jldoctests)

This page describes how to write and maintain `jldoctest` blocks in the documentation. Following these guidelines helps keep doctests reliable and easy to read.

## Filters

Use `filter =` whenever output contains text that might vary across runs.
The following are common situations where this may happen:

- The output contains arrays with undefined memory (e.g. from `undef` or `similar`)
- The output contains random numbers
- The output contains timing information
- The output contains file system paths


### Common filter sequences

The documentation relies on several recurring patterns:
- `r"int.jl:\\d+"` — remove line numbers from introspection macros.
- `r"Stacktrace:(\\n \\[0-9]+\\].*)*"` — hide stack traces when illustrating
  errors.
- `r"Closest candidates.*\\n  .*"` — skip the method suggestions printed by
  `MethodError`.
- `r"@ .*"` — strip file locations from the output of `methods` or
  `@which`.
- `r"\\@world\\(MyStruct, \\d+:\\d+\\)"` — filter world age numbers.
- `r"with \\d+ methods"` — ignore method counts when redefining functions.
- `r"[0-9\\.]+ seconds \\(.*?\\)"` — remove timing output with memory
  information.
- `r"[0-9\\.]+ seconds"` — remove simple timing results.
- `r"[0-9\\.]+"` — filter digits from names such as anonymous functions.
- `r"([A-B] [0-5])"` and `r"[A-B] [X-Z] [0-5]"` — account for non-deterministic
  process output.
- `r"(world\\nhello|hello\\nworld)"` — allow either ordering of interleaved
  output.

If none of these match your situation, craft a regular expression that
removes the varying text. Using filters keeps doctests stable across
platforms and Julia versions.

!!! note "Double escaping in docstrings"
    When writing regex filters inside docstrings, remember to double escape
    backslashes. For example, use `r"[\\d\\.]+"` instead of `r"[\d\.]+"`.
    This is necessary because the docstring itself processes escape sequences
    before the regex is created.

## Setup code

Small setup expressions may be placed inline using the `setup =` option:

````
```jldoctest; setup = :(using InteractiveUtils)
...
```
````

For longer setup code or if multiple blocks require the same environment, use the
`DocTestSetup` meta block:

````
```@meta
DocTestSetup = :(import Random; Random.seed!(1234))
```
````

and disable it afterwards with

````
```@meta
DocTestSetup = nothing
```
````

### Teardown code

If you need teardown code (e.g. to delete created temporary files or to reset
the current directory), you can use the `teardown =` option:

````
```jldoctest; setup = :(oldpath = pwd(); cd(mktempdir())), teardown = :(cd(oldpath))
...
```
````

## Maintaining state between snippets

Related doctest blocks can share state by giving them the same label after the
`jldoctest` keyword. The manual uses this pattern to demonstrate mutation:

````
```jldoctest mutation_vs_rebind
julia> a = [1,2,3]
...
```
````

and later

````
```jldoctest mutation_vs_rebind
julia> a[1] = 42
...
```
````

Blocks with the same name execute sequentially during doctesting, so variables
created in the first block remain available in the following ones.

When a snippet needs to preserve its result for later examples, give it a label
and reuse that label. This avoids repeating setup code and mirrors a REPL
session more closely.

## Syntax versioning

When documenting features that use new Julia syntax, you can specify the required
syntax version for a doctest block using the `syntax =` option:

````
```jldoctest; syntax = v"1.14"
julia> result = @label myblock begin
           for i in 1:10
               i > 5 && break myblock i * 2
           end
           0
       end
12
```
````

This ensures the code block is parsed using the specified Julia syntax version,
allowing doctests for new language features to pass even when the documentation
is built with an older default syntax.

For modules that predominantly use new syntax, you can set a global default
using `DocTestSyntax` in a meta block:

````
```@meta
DocTestSyntax = v"1.14"
```
````

Per-block `syntax =` settings override the global `DocTestSyntax` setting.

!!! compat "Julia 1.14"
    Syntax versioning for doctests requires Julia 1.14 or later.
    When running doctests on older Julia versions, blocks with `syntax = v"1.14"`
    or higher will be skipped with a warning.

## Further reading
For a complete reference of doctest syntax, see the [corresponding Documenter.jl docs](https://documenter.juliadocs.org/stable/man/doctests/).
