Hacking on the wrap-nix-shell source code

Python

Running the test suite

The easiest way to run the wrap-nix-shell test suite is to change into the python/ directory and use the tox-stages utility from the test-stages package:

tox-stages run

This, especially if run from a Python environment which also has the tox-uv module installed, will run several static checkers (linters) and then, if they are all successful, it will also run the Python unit test suite.

A more traditional way is to use tox itself (version 4.1 or higher):

tox run-parallel

Keeping the test suite in sync

The Rust and Python implementations of wrap-nix-shell use some common files in their test suite. The "source of truth" for these files is the test-data/ subdirectory of the python/ directory; at the cost of some data duplication, it is also copied in full as rust/test-data/. The Python test suite tries to detect whether it is being run from a subdirectory of the full wrap-nix-shell source tree (it looks for a couple of marker files and directories in the parent directory), and if it is, it also tries to make sure that the rust/ copy of the test data is identical.

Thus, any changes to python/test-data/ must also be applied to rust/test-data/, although they should be committed separately in a "sync the test data" commit.

Rust

Running the Rust test suite

To run the unit tests defined in the Rust source code, run cargo test as usual in the rust/ directory.

Running the Python functional test suite

After making any changes to the Rust implementation of wrap-nix-shell, the Python functional test should be run to ensure that the command-line tool still complies with the common expectations.

The easy way

The easiest way to do that is to run the run-functional-test.sh tool in the rust/ directory:

./run-functional-test.sh

If passed the -r command-line option, the tool will test the release build (target/release/wrap-nix-shell) instead of the debug one.

The gory details

To run the Python functional test suite against the Rust wrap-nix-shell implementation, the WRAP_NIX_SHELL_PROGRAM environment variable must be set to the full path to the built Rust executable (see the Python section above for a discussion of tox-stages):

cd ../python/
env WRAP_NIX_SHELL_PROGRAM="$(pwd)/../rust/target/debug/wrap-nix-shell" tox-stages run

Note that this command will run the full Python test suite, also running tests that have nothing to do with the wrap-nix-shell executable. To really narrow things down, pass more command-line parameters to tox-stages so that it will pass them to Tox itself:

cd ../python/
env WRAP_NIX_SHELL_PROGRAM="$(pwd)/../rust/target/debug/wrap-nix-shell" \
    tox-stages run \
    -A -- -A -k -A 'test_functional' \
    'unit-tests-pytest-8'

Or, of course, this can be run using Tox itself:

cd ../python/
env WRAP_NIX_SHELL_PROGRAM="$(pwd)/../rust/target/debug/wrap-nix-shell" \
    tox run-parallel \
    -e 'unit-tests-pytest-8' \
    -- -k 'test_functional'

The last two snippets are exactly what run-functional-test.sh does depending on whether it can find tox-stages (or $TOX_STAGES if set beforehand) or tox (or $TOX if set beforehand) as a program that may be executed.