Release of tytanic 0.1.0

What’s Tytanic?

Tytanic is the successor to the now archived Typst-test program, it allows you to manage, compile and compare regression tests for Typst projects and packages. Here’s it running the cetz test suite:

It currently targets Typst 0.12.x and is reasonably stable. It comes in both rust-library crate and CLI form, although the library crate needs polishing for more general use.

Panic Tests

Because Tytanic targets Typst as a library and comes with its own compiler, it can do some things regular test scripts can’t, it can catch panics for you and lets you inspect them. Tytanic comes with the regular a standard library as you know and love it, i.e. it has grid, figure, ref, etc., but it also has catch and assert-panic to give you the ability to test your failure paths.

You can write a test case such as:

#import "/src/lib.typ": foo

// doesn't panic
#assert.eq(catch(() => foo(auto)), none)

// panics with the expected message
#assert.eq(catch(() => foo(none)), "panicked with: `none` is not valid")

// sometimes it's enough to know that this panics at all
#assert-panic(() => foo(none))

Regression tests

Because Typst is fundamentally about placing content in a document, packages often want to ensure that their output stays the same across changes to their code base versions, regression tests are test scripts which are compared to reference documents to catch changes in visual output of a package.

You can create three kinds of tests:

  • compile-only, as the name implies, these simply check that your code keeps compiling.
    These are most helpful when you simply want to test the scripting related API of your package.
  • ephemeral, these tests compile two documents and compare their output.
    Ephemeral tests are useful if you want to recreate some output in your package and ensure it matches some other output, like default-show rules or certain package compatibilities.
  • persistent, the most common type of test, these have references which persist on disk between test runs and need manual updates when their output changes.
    Such tests help you ensure consistent output between different Typst versions or different versions of your package.

Test set filtering

Tytanic comes with a test set DSL inspired by Jujutsu and cargo-nextest. Test sets allow you to filter tests using a functional language in which you compose sets of tests using functions and operators.

If you want to only run ephemeral tests but without those found in tests/regressions you could do this using:

tt run -e 'ephemeral() ~ r:regressions'

Documentation

Check out the book to get started and learn more about its features.

Installation

Tytanic can be installed using cargo install tytanic or by downloading one of the release artifacts from the GitHub repository release page.

17 Likes