1. Introduction
  3. Editor Integration
  4. Common Configurations
  5. 1. Editor Frontends
    1. 1.1. VS Cod(e,ium)
    2. 1.2. Neovim
    3. 1.3. Emacs
    4. 1.4. Sublime Text
    5. 1.5. Helix
    6. 1.6. Zed
  8. Features
  9. 2. Command line interface
  10. 3. Code Documentation
  11. 4. Code Completion
  12. 5. Exporting Documents
  13. 6. Document Preview
  14. 7. Testing
  15. 8. Other Features
  17. Service Overview
  18. Overview of Service
  19. 9. Principles
  20. 10. Commands System
  21. 11. LSP Inputs
  22. 12. Type System
  24. Service Development
  25. 13. Crate Docs
  26. 14. LSP and CLI
  27. 15. Language Queries
  28. 16. Document Preview

Tinymist Docs

The testing feature is available since tinymist v0.13.10.

#

IDE Support

You can run tests and check coverage in the IDE or CLI.

#

Test Discovery

Given a file, tinymist will try to discover tests related to the file.

  • All dependent files in the same workspace will be checked.

    • For example, if file a.typ contains import "b.typ" or include "b.typ", tinymist will check b.typ for tests as well.

  • For each file including the entry file itself, tinymist will check the file for tests.

    • If a file is named example-*.typ, it is considered an example document and will be compiled using typst::compile.

      • Both png export and html export may be called.
      • For now, png export is always called for each example file.
      • If the label <test-html-example> can be found in the example file, html export will be called.

    • Top-level functions will be checked for tests.

      • If a function is named test-*, it is considered a test function and will be called directly.
      • If a function is named bench-*, it is considered a benchmark function and will be called once to collect coverage.
      • If a function is named panic-on-*, it will only pass the test if a panic occurs during execution.

Example Entry File:

1
#import "example-hello-world.typ"
2

3
#let test-it() = {
4
  "test"
5
}
6

7
#let panic-on-panic() = {
8
  panic("this is a panic")
9
}
1
#import "example-hello-world.typ"
2

3
#let test-it() = {
4
  "test"
5
}
6

7
#let panic-on-panic() = {
8
  panic("this is a panic")
9
}

Example Output:

1
Running example(example-hello-world)
2
Running test(test-it)
3
Running test(panic-on-panic)
4
 Passed test(test-it)
5
 Passed test(panic-on-panic)
6
 Passed example(example-hello-world)
7
   Info All test cases passed...
1
Running example(example-hello-world)
2
Running test(test-it)
3
Running test(panic-on-panic)
4
 Passed test(test-it)
5
 Passed test(panic-on-panic)
6
 Passed example(example-hello-world)
7
   Info All test cases passed...

#

Benchmarking

Since it requires some heavy framework to run benchmarks, a standalone tool is provided to run benchmarks.

Check crityp for more information.

#

Visualizing Coverage

  • Run and collect file coverage using command tinymist.profileCurrentFileCoverage in VS Cod(e,ium).

  • Run and collect test coverage using command tinymist.profileCurrentTestCoverage in VS Cod(e,ium).

    • Check Test Discovery to learn how tinymist discovers tests.

VS Cod(e,ium) will show the overall coverage in the editor.

#

CLI Support

You can run tests and check coverage in the CLI.

1
tinymist test tests/main.typ
2
...
3
  Info: All test cases passed...
1
tinymist test tests/main.typ
2
...
3
  Info: All test cases passed...

You can pass same arguments as typst compile to tinymist test.

To watch for changes and run tests automatically, use the --watch option:

1
tinymist test --watch tests/main.typ
1
tinymist test --watch tests/main.typ

When running in the watch mode, input command lines to control the test runner:

1
   Hint Press 'h' for help
2
$ h
3
h/r/u/c/q: help/run/update/quit
1
   Hint Press 'h' for help
2
$ h
3
h/r/u/c/q: help/run/update/quit

For example, according to the help message, update the reference files using the command u (update).

#

Collecting Coverage with CLI

You can collect coverage using the --coverage option.

1
tinymist test tests/main.typ --coverage
2
...
3
   Info Written coverage to target/coverage.json ...
4
    Cov Coverage Summary 9/10 (90.00%)
5
   Info All test cases passed...
1
tinymist test tests/main.typ --coverage
2
...
3
   Info Written coverage to target/coverage.json ...
4
    Cov Coverage Summary 9/10 (90.00%)
5
   Info All test cases passed...

Use --print-coverage=full to print the coverage of each file.

1
tinymist test tests/main.typ --coverage --print-coverage=full
2
...
3
    Cov  6     / 6     (100.00%)  tests/example-hello-world.typ
4
    Cov  3     / 4     ( 75.00%)  tests/main.typ
5
    Cov Coverage Summary 9/10 (90.00%)
6
   Info All test cases passed...
1
tinymist test tests/main.typ --coverage --print-coverage=full
2
...
3
    Cov  6     / 6     (100.00%)  tests/example-hello-world.typ
4
    Cov  3     / 4     ( 75.00%)  tests/main.typ
5
    Cov Coverage Summary 9/10 (90.00%)
6
   Info All test cases passed...

#

Debugging tests with CLI

If any test fails, the CLI will return a non-zero exit code.

1
tinymist test tests/main.typ
2
...
3
 Fatal: Some test cases failed...
1
tinymist test tests/main.typ
2
...
3
 Fatal: Some test cases failed...

To update the reference files, you can run:

1
tinymist test tests/main.typ --update
1
tinymist test tests/main.typ --update

To get image files to diff you can use grep to find the image files to update:

1
tinymist test tests/main.typ 2> >(grep Hint) > >(grep "compare image")
2
   Hint example(example-hello-world): compare image at refs/png/example-hello-world.png
3
   Hint example(example-other): compare image at refs/png/example-other.png
1
tinymist test tests/main.typ 2> >(grep Hint) > >(grep "compare image")
2
   Hint example(example-hello-world): compare image at refs/png/example-hello-world.png
3
   Hint example(example-other): compare image at refs/png/example-other.png

You can use your favorite image diff tool to compare the images, e.g. magick compare.

#

Tips: Reproducible Rendering

To ensure that the rendering is reproducible, you can ignore system fonts.

1
tinymist test tests/main.typ --ignore-system-fonts
1
tinymist test tests/main.typ --ignore-system-fonts

Adds font paths using the --font-paths option if you want to use custom fonts:

1
tinymist test tests/main.typ --font-paths /path/to/fonts
1
tinymist test tests/main.typ --font-paths /path/to/fonts

#

Continuous Integration

tinymist test only compares hash files to check whether content is changed. Therefore, you can ignore rendered files and only keep the hash files to compare them on CI. Putting the following content in .gitignore will help you to ignore the files:

1
# png files
2
refs/png/**/*.png
3
# html files
4
refs/html/**/*.html
5
# hash files
6
!refs/**/*.hash
1
# png files
2
refs/png/**/*.png
3
# html files
4
refs/html/**/*.html
5
# hash files
6
!refs/**/*.hash

Install tinymist on CI and run tinymist test to check whether the content is changed.

1
- name: Install tinymist
2
  env:
3
    TINYMIST_VERSION: 0.13.x # to test with typst compiler v0.13.x, tinymist v0.14.x for typst v0.14.x, and so on.
4
  run: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Myriad-Dreamin/tinymist/releases/download/${TINYMIST_VERSION}/tinymist-installer.sh | sh
5
- name: Run tests (Typst)
6
  run: tinymist test tests/main.typ --root . --ppi 144 --ignore-system-fonts
7
- name: Upload artifacts
8
  uses: actions/upload-artifact@v4
9
  with:
10
    name: refs
11
    path: refs
1
- name: Install tinymist
2
  env:
3
    TINYMIST_VERSION: 0.13.x # to test with typst compiler v0.13.x, tinymist v0.14.x for typst v0.14.x, and so on.
4
  run: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Myriad-Dreamin/tinymist/releases/download/${TINYMIST_VERSION}/tinymist-installer.sh | sh
5
- name: Run tests (Typst)
6
  run: tinymist test tests/main.typ --root . --ppi 144 --ignore-system-fonts
7
- name: Upload artifacts
8
  uses: actions/upload-artifact@v4
9
  with:
10
    name: refs
11
    path: refs