gleedoc - v1.0.0

gleedoc

Types

GleedocConfig

</>

Configuration for a gleedoc run.

pub type GleedocConfig {
  GleedocConfig(
    extra_imports: List(String),
    source_dir: String,
    output_dir: String,
    preserve_tests: Bool,
    source_mapped_errors: Bool,
  )
}

Constructors 

  • GleedocConfig(
  extra_imports: List(String),
  source_dir: String,
  output_dir: String,
  preserve_tests: Bool,
  source_mapped_errors: Bool,
)

    Arguments

    extra_imports

    A list of imports that will automatically be applied to every generated test file. Example: ["gleam/int", "gleam/otp/actor"]

    source_dir

    Directory to read source files from, typically "src"

    output_dir

    Directory to write generated tests to, typically "test"

    preserve_tests

    Whether to preserve generated test files in output_dir after doc tests finish. If you are running gleedoc.run programmatically, please always set this to True.

    source_mapped_errors

    Whether to annotate each generated assert with as "file:line", pointing back to the exact source line of the assertion in the doc comment. When True (the default), test failures are reported against the original source file/line rather than the generated test file.

Values

add_extra_import

</> 
pub fn add_extra_import(
  config: GleedocConfig,
  import_path: String,
) -> GleedocConfig

Add a single import to extra_imports. Convenient when chaining multiple imports through the builder pipeline.

Example

gleedoc.new()
|> gleedoc.add_extra_import("gleam/int")
|> gleedoc.add_extra_import("gleam/string")

default

</> 
pub fn default() -> GleedocConfig

Returns a GleedocConfig populated with sensible defaults:

  • source_dir: "src"
  • output_dir: "test"
  • extra_imports: []
  • preserve_tests: False
  • source_mapped_errors: True

main

</> 
pub fn main() -> Nil

Entry point for gleam run -m gleedoc. It’s essentially executing the run function using the default config with preserve_tests set to True.

let config = GleedocConfig(..default(), preserve_tests: True)

new

</> 
pub fn new() -> GleedocConfig

Start a new GleedocConfig builder using the same defaults as default. Intended to be the entry point of the builder pipeline:

Example

gleedoc.new()
|> gleedoc.with_source_dir("src")
|> gleedoc.run

run

</> 
pub fn run(config: GleedocConfig) -> Result(Nil, snag.Snag)

Run gleedoc on a project, extracting doc tests from source files and generating test files in the output directory.

Example

import gleedoc

pub fn main() {
  let config =
    gleedoc.GleedocConfig(
      output_dir: "test/integration",
      source_dir: "dev/fixtures",
      extra_imports: ["gleam/int"],
      preserve_tests: True,
      source_mapped_errors: True,
    )
  let assert Ok(_) = gleedoc.run(config)
}

run_with

</> 
pub fn run_with(
  config: GleedocConfig,
  test_main: fn() -> Nil,
) -> Nil

Run gleedoc with gleeunit.main, so one gleam test command will take care of both doc tests and unit tests.

Example

import gleedoc
import gleeunit

pub fn main() {
  gleedoc.default() |> gleedoc.run_with(gleeunit.main)
}

with_extra_imports

</> 
pub fn with_extra_imports(
  config: GleedocConfig,
  extra_imports: List(String),
) -> GleedocConfig

Replace the list of extra imports added to every generated test file.

To add a single import instead of replacing the whole list, use add_extra_import.

with_output_dir

</> 
pub fn with_output_dir(
  config: GleedocConfig,
  output_dir: String,
) -> GleedocConfig

Set the directory gleedoc writes generated tests to.

with_preserve_tests

</> 
pub fn with_preserve_tests(
  config: GleedocConfig,
  preserve_tests: Bool,
) -> GleedocConfig

Set whether generated test files should be preserved in output_dir after doc tests finish.

with_source_dir

</> 
pub fn with_source_dir(
  config: GleedocConfig,
  source_dir: String,
) -> GleedocConfig

Set the directory gleedoc reads source files from.

with_source_mapped_errors

</> 
pub fn with_source_mapped_errors(
  config: GleedocConfig,
  source_mapped_errors: Bool,
) -> GleedocConfig

Set whether each generated assert should be annotated with as "file:line", so test failures are reported against the original source file and line.

✨ Search Document