Subplot → blog → 2025 → Subplot 0.13.0 released

The Subplot project announces the 0.13.0 release of the tool for documenting acceptance criteria and verifying them automatically. See below for a summary of changes in this release, and NEWS.md in the git repository for release notes for all releases.

Version 0.13.0, released 2025-08-02

Deprecation changes:

  • We are now officially deprecating subplot-build in favour of subplotlib::codegen!() - in later versions we will stop publishing subplot-build.

    To make this change, you should no longer use subplot-build at all, and instead in your tests/foo.rs files where you previously did include!(...) you should call subplotlib::codegen!("foo.subplot") instead. See the macro's documentation for acceptable argument forms.

Breaking changes:

  • We have deleted the bash template. If you have projects which used it then you can dig it out of our git repository and embed the template into your project. However we strongly recommend that you translate your scenario suite into Python or Rust.

Bug fixes:

  • The Runcmd scenario context object in the Rust step library has gained a .with_forklock() method which can be used to reduce the likelihood of flakiness introduced by threaded test suites and forking subprocesses to run scripts newly written out by scenarios.

  • The error message for a step not being found in any bindings file now reports the location of the step.

  • The lib/files step library now enforces that all filenames captured from the step text are relative to the data directory for the scenario execution.

  • The Rust implementation of the lib/runcmd step library has been clarified that it runs commands in the scenario datadir, not the source tree.

  • The Rust implementation of the lib/runcmd of the step "when I run, in {dir}, ..." no longer sets the HOME environment variable to dir.

New features:

  • Scenarios can be labelled using a label=foo attribute in the first block of steps in a scenario.

  • The metadata subcommand now provides information about scenario labels. This changes the JSON format slightly.

  • The lib/runcmd library now supports steps to set and unset environment variables.

  • Subplot now has groundwork to support filtering scenarios. Actual filters will come later.

  • The lib/files step library now had steps for removing files and empty directories.

  • The lib/files step library now has steps to compare an on-disk file for equality with another on-disk file or an embedded file.

  • The lib/runcmd step library now has a step "then I can run...", similar to "when I run...", but as a "then". This will make it more natural to use in some circumstances.

  • The lib/runcmd step library now supports the standard input to be redirected.

Other changes:

  • Name slugs (eg. test function names) now pass digits through, will automatically prefix with n_ if the slug would otherwise start with a digit; and will suffix with _NNN where NNN is selected to make the name unique. Ordering of scenarios is not guaranteed to remain stable, so it's always better to come up with unique names for scenarios rather than relying on this last feature.

  • Subplot's build system uses pandoc to construct step library manuals.

  • The README.md and other documentation is clearer and up to date on how to actually run Subplot and its test suite. The ./check script has been replaced with Makefile for clarity.

  • Various error messages have been clarified.