Skip to content

Testing

Installing into a test environment

You will probably want to test your generated conda packages before deploying them. Currently, conda install only supports installing conda package files without their dependencies, so whl2conda provides an install subcommand to install one or more package files into a test environment along with their dependencies:

$ whl2conda install mypackage-1.2.3-py_0.conda -n test-env

If you want to create an environment in a temporary directory:

$ whl2conda install mypackage-1.2.3-py_0.conda --create -p tmp-dir

You can also add additional dependencies or other options to pass to the underlying conda install command:

$ whl2conda install mypackage-1.2.3-py_0.conda \
   --create -p tmp-dir \
   --extra pytest -c my-channel

If you are building multiple packages with an interdependency you should install them in a single install command, e.g.:

$ whl2conda install mypackage-1.2.3-py_0.conda mycorepackage-1.2.3-py_0.conda ...

Running package tests

The whl2conda test command automates the install-and-test cycle: it creates a fresh environment, installs the package and any test requirements into it, runs the specified tests, and removes the environment:

$ whl2conda test dist/mypackage-1.2.3-py_0.conda

The tests are taken from, in order of precedence:

  • a YAML file given with --test-file, containing a v1 recipe tests list (either a bare list or a mapping with a tests key),
  • the [[tool.whl2conda.tests]] section of the project's pyproject.toml (see the pyproject guide), or
  • the test section of a conda recipe (meta.yaml or recipe.yaml) in the project directory, which will be rendered first.

The project directory defaults to the current directory and may be given as a second argument:

$ whl2conda test dist/mypackage-1.2.3-py_0.conda conda.recipe

To test against specific python versions (for example, to check the boundaries of a noarch: python package's python requirement), use one or more --python options, or the test-python setting in pyproject.toml; the tests are run once per version:

$ whl2conda test dist/mypackage-1.2.3-py_0.conda --python 3.10 --python 3.14

Additional channels for the test environment can be supplied with -c/--channel, --keep-test-env retains the environment for debugging, and --dry-run shows the tests that would be run. The command exits with a non-zero status if any test fails, so it can be used in scripts and CI. See the command reference for all options.

Installing into conda-bld

Once you are done testing, you may upload your package to a conda channel using the appropriate tool (e.g. anaconda upload or curl), or you may install into your local conda-bld directory to support conda install --use-local. You can do this using:

$ whl2conda install mypackage-1.2.3-py_0.conda --conda-bld

Comparing packages

You may wish to compare generated packages against those generated by conda-build or rattler-build (e.g. from conda-forge) in order both to understand what this tool is doing and to verify that nothing important is missing. You can do this with the whl2conda diff command:

$ whl2conda diff \
   dist/mypackage-1.2.3-py_0.conda \
   ~/miniforge3/conda-bld/noarch/mypackage-1.2.3-py_0.tar.bz2

By default, this semantically analyzes the differences between the two packages and prints a report of notable and unexpected differences — missing dependencies, missing or altered files, unrenamed pip dependencies, mismatched entry points, and so on — while suppressing differences that are expected when comparing a whl2conda-generated package against a recipe-built one, such as differing build strings and timestamps, run-export dependencies added by compilers, regenerated entry point scripts, differing binary module contents, and dist-info bookkeeping details. The command exits with a non-zero status if any unexpected differences are found, so it can be used in scripts and CI.

Useful options (see the command reference for the full list):

  • --all also shows the expected differences
  • --strict treats notable differences as errors
  • --ignore <category> suppresses a category of differences
  • --run-export <name> treats additional dependency names as benign run-exports when only present in the reference package
  • --json emits the analysis as JSON

Alternatively, you can inspect the raw differences with your favorite directory diff tool using the -T option. This will unpack the packages into temporary directories, normalize the metadata files to minimize mismatches and run the specified diff tool with the given arguments:

$ whl2conda diff \
   dist/mypackage-1.2.3-py_0.conda \
   ~/miniforge3/conda-bld/noarch/mypackage-1.2.3-py_0.tar.bz2 \
   -T kdiff3