Crate texlang_testing

Crate texlang_testing 

Source
Expand description

Texlang unit testing library

This is a crate for writing unit tests for code that uses Texlang. It is used extensively in the Texlang standard library, so the unit tests there are good examples of what this crate can do. This crate is designed to be used outside of the Texlang project, and work for any Rust code that uses Texlang.

§Basic setup

As is common in all Texlang code, each unit test built with this library works with a specific user-defined Texlang state type. This state type is provided by the unit test writer. In addition to implementing the TexlangState trait, this state must also:

  1. Include the TestingComponent type as a component. I.e., the state must implement the HasComponent<TestingComponent> trait.

  2. Configure the recoverable_error_hook method on the TexlangState trait to invoke TestingComponent::recoverable_error_hook.

  3. Implement Default.

If the unit test doesn’t require anything else from the state, the State type defined in this library can simply be used. This type satisfies all the conditions above.

§Test types

The crate offers a few different types of tests.

§Expansion equality tests

Run using run_expansion_equality_test.

These tests verify that two different TeX snippets expand to the same output. For example, an output equality test can verify that

\def\HelloWorld{Hola Mundo}\HelloWorld - \HelloWorld

and

Hola Mundo - Hola Mundo

produce the same output.

In this example the second input is just a constant, which is usually how these tests are used. We generally use these tests to verify some non-trivial TeX expression (like a \def macro definition) evaluates to a specific constant output.

These tests do not verify that the state of the VM is the same in both cases. In fact the state is usually different; for example, in the first snippet above the macro \HelloWorld will be defined in the state but won’t be in the second snippet.

§Failure tests

Run using run_fatal_error_test.

These tests verify that a specific TeX snippet fails to execute.

§Serde tests

Run using run_serde_test.

These tests verify that the Texlang state being used can be successfully serialized and deserialized in the middle of executing a TeX snippet.

A serde test accepts two TeX snippets, A and B. It first runs the VM for the concatenated snippet AB and saves the result. It then initializes a new VM and performs the following steps:

  • Runs the snippet A
  • Serializes and deserialized the VM, using a specified format.
  • Runs the snipped B in the deserialized VM.

The test verifies that the result from this is the same as the result from the VM for the concatenated snippet AB.

§The test suite macro

All of the test types can be run using the run functions described above (e.g., run_fatal_error_test). However the preferred way to write a suite of unit tests is to use the test_suite macro. This macro removes a bunch of boilerplate and makes it easy to add new test cases.

See the macro’s documentation for instructions on using it. Also the Texlang standard library uses this macro extensively.

Macros§

test_suite
Macro to generate a suite of unit tests

Structs§

State
Simple state type for simple unit tests.
TestingComponent
Texlang component that every unit testing state needs to have.

Enums§

SerdeFormat
Format to use in a serde test.
TestOption
Option passed to a test runner.

Functions§

run_expansion_equality_test
Run an expansion equality test.
run_fatal_error_test
Run a failure test.
run_serde_test
Run a serialization/deserialization test
run_state_test
Run a state verification test.