Crate derive_deftly_tests

Source
Expand description

Tests for derive-deftly

Internal, unpublished crate.

Separating these tests into their own crate arranges that they can go through the “front door” of use derive_deftly::..., and in particular makes the cross-crate tests uniform with the others.

§Invoking the tests

When running the full test suite, you should use a particular version of Nightly Rust:

rustup toolchain add nightly-2024-06-06
cargo +nightly-2024-06-06 test --locked --workspace --all-features

With other versions, the pretty printing of the macro expansions, or the results of standard library macros, can change, causing the tests to break.

After your first run, it will probably be helpful to say

CARGO_NET_OFFLINE=true cargo +nightly-2024-06-06 test --locked --workspace --all-features

This is because otherwise cargo will uselessly re-update the cargo index, when it is reinvoked by some of the tests.

§Updating the expected outputs

Many of the test cases compare an actual with expected output. For example, an expected macro expansion, or error message.

If this is expected (for example, you added to the tests, or fixed a bug) can update the expected output files from the actual output.

TRYBUILD=overwrite MACROTEST=overwrite STDERRTEST=overwrite \
CARGO_NET_OFFLINE=true cargo +nightly-2024-06-06 test --locked --workspace --all-features

Check that the actual output is as desired! This is easily done with git diff before committing.

§Slight discrepancies in output, due to reformatting unfaithfulness

The outputs in tests/expand/ come from cargo expand, which reformats them for legibility. This reformatting is not always 100% faithful. For example, it can insert or remove :: tokens.

The output from dbg_all_keywords is completely faithful. This appears in tests/stderr/recent.real-stderr, for example.

See #13 for some more discussion.

§Classes of test in the derive-deftly workspace

Testing proc macros is not entirely straightforward, so there are multiple classes of test with different approaches.

§tests/expand/*.rs

  • Run with trybuild, and expected to pass.
  • Expanded with macrotest, compared with expand/*.expanded.rs.

Invoked from tests/macrotest.rs, using list_expand_test_paths and list_expand_test_paths_for_macrotest.

Tests with recent somewhere in their name are only run if the recent cargo feature is enabled for derive-deftly-tests. This is enabled in CI for the newer compilers, but not for the MSRV.

§tests/ui/*.rs

  • Run with trybuild and expected to fail.
  • Errors compared with tests/ui/*.stderr.

Invoked from tests/trybuild.rs.

Some of these .rs files are reused for tests/stderr/.

§tests/minimal-ui/*.rs

As above, but used when feature full isn’t enabled. This just tests errors from features being disabled. (In the tests, we include beta in full.)

§tests/stderr/

Test cases listed in tests/stderr/stderr-lib.rs.

  • Compile attempted, and stderr captured
  • Output compared with tests/stderr/combined.real-stderr

Invoked from tests/stderr.rs, which builds the crate derive-deftly-stderr-tests. See the doc comment there for details and rationale.

§tests/pub-a/, tests/pub-b/

Tests of cross-crate exports of macros and templates. pub-a exports things, and pub-b imports and uses them.

pub-a uses a special bizarre version of derive-deftly, to test that the right template expander is used in each case. See the pub-b doc comment for details.

§tests/compat/

Tests compatibility with old, published, versions of derive-deftly. See tests/compat/README.md.

§The normal-ish #[cfg(test)] modules listed in here tests/tests.rs

Each module is compiled, and its #[test] functions are run.

§tests/directly/

Tests that go through the “back door”, to use the innards of derive-deftly.

Currently this is the tests in directly::check_examples which extract examples from doc/reference.md and check that they match real output.

Re-exports§

Modules§

  • tutils
    utilities and common code for testingy

Macros§

  • m
    fn m!(l: &str, re: &str) -> bool: does regexp re match in l ?
  • mc
    fn mc!(l: &str, re: &str) -> Option<(CAP,...)>: regexp captures?
  • re
    fn re!(l: &str) -> Regex