Advanced Usage

Configuration file

Suppose you want to test upgrades for a subset of your dependencies. Instead of letting edgetest parse your requirements file, you can create a configuration file:

[edgetest.envs.pandas]
upgrade =
    pandas

Then run

$ edgetest -c edgetest.cfg

This command will

1. Create your virtual environment (as in the standard case),

2. Install the local package,

3. Upgrade pandas, and

4. Run the pytest in the environment.

Important

This configuration file can be a standalone file which is distinct from the setup.cfg or pyproject.toml configurations. Just note it must have a edgetest.envs otherwise it expects a PEP 517-style setup.cfg

setup.cfg and pyproject.toml Configuration

You can also specify your testing environment through setup.cfg or pyproject.toml:

.cfg.toml

[edgetest.envs.pandas]
upgrade =
    pandas

If you’re using a PEP-517 or PEP-621 style installation configuration your requirements might look like this:

.cfg.toml

[options]
install_requires =
    pandas

To point to setup.cfg or pyproject.toml, supply the location of the file as your --config:

.cfg.toml

$ edgetest -c path/to/setup.cfg

Important

Using setup.cfg or pyproject.toml will allow you to upgrade optional installations.

Installing extras

To install extras with your local package in the virtual environment(s), modify your configuration or CLI call as follows:

.cfg.tomlRequirements parsing

Add an extras list to your environment:

[edgetest.envs.pandas]
upgrade =
    pandas
extras =
    tests

Modifying the test command

To customize your test command, modify the configuration or CLI call as follows:

.cfg.tomlRequirements parsing

Add a command key to your environment:

[edgetest.envs.pandas]
upgrade =
    pandas
extras =
    tests
command =
    pytest tests -m 'not integration'

Additional dependencies

Suppose your testing requires an additional library that is not included in your extras. You can specify additional dependencies to be installed via pip.

To specify additional pip dependencies, modify as follows:

.cfg.tomlRequirements parsing

Add a deps list:

[edgetest.envs.pandas]
upgrade =
    pandas
extras =
    tests
command =
    pytest tests -m "not integration"
deps =
    scikit-learn

In both cases, scikit-learn will be installed with the following command:

$ .edgetest/pandas/bin/python -m pip install scikit-learn

Default arguments

If you have default arguments you want to pass to each environment in your configuration, you can specify those under the edgetest section of your configuration:

.cfg.toml

[edgetest]
extras =
    tests
command =
    pytest tests -m 'not integration'

[edgetest.envs.pandas]
upgrade =
    pandas

[edgetest.envs.numpy]
upgrade =
    numpy

Important

You can combine your configuration file with requirements.txt. If you have the following configuration file:

[options]
install_requires =

[edgetest]
extras =
    tests
command =
    pytest tests -m 'not integration'

and the following requirements file:

pandas>=0.25.1,<=1.0.0
scikit-learn>=0.23.0,<=0.24.2

the following CLI call

$ edgetest -c edgetest.cfg -r requirements.txt

will apply the default arguments to each environment.

Multiple packages

Suppose you have multiple local packages you want to test. You can include the package_dir in your testing project directory:

.cfg.toml

[edgetest.envs.pandas]
package_dir = ../mypackage
upgrade =
    pandas

[edgetest.envs.numpy]
package_dir = ../myotherpackage
upgrade =
    numpy

After running

$ edgetest -c path/to/edgetest.cfg

your end output should look something like this:

============= =============== =================== =================
 Environment   Passing tests   Upgraded packages   Package version
------------- --------------- ------------------- -----------------
 pandas        True            pandas              1.2.4
 numpy         True            numpy               1.20.2
============= =============== =================== =================

Important

Testing multiple local packages is only supported with the configuration file syntax.

Running a single environment

To run edgetest for a single environment, supply --environment or -e:

$ edgetest -e pandas

Exporting an upgraded config file

.cfg.toml

This will overwrite your current setup.cfg file with the updated requirements.

$ edgetest -c /path/to/setup.cfg --export

Exporting an upgraded requirements file

You can use the --export flag to overwrite your input requirements file with the upgraded version as well. This feature will update the --requirements argument file (default requirements.txt) with the upgraded packages from your last test environment if the tests pass. In the requirements file,

• any <= constraint will be updated,

• any == constraint will be changed to >= and <=, and

• any < constraint will use != to exclude the upper version but include the new maximum.

For instance, snowflake-connector-python[pandas]>=2.2.8,<2.3.9 might be replaced with snowflake-connector-python[pandas]!=2.3.9,<=2.4.3,>=2.2.8. To use this functionality,

Configuration file (cfg/toml)Requirements parsing

Include the correct --requirements filepath and use --export:

$ edgetest \
    -c path/to/edgetest.cfg \
    --requirements requirements.txt \
    --export

Testing lower bounds of packages

Warning

This feature is experimental and may change in future releases. Limited functionality is available.

Suppose you want to test if a new feature is compatible with dependencies’ lower bounds. You can use an edgetest environment to test the lower bounds of dependencies in your setup.cfg or pyproject.toml as follows:

.cfg.toml

[edgetest.envs.pandas_lower]
lower =
    pandas

Running the edgetest command using this environment specification will:

1. Create your virtual environment (as in the standard case),

2. Install the local package,

3. Install the lower version of pandas as specified in your project configuration file, and

4. Run the pytest in the environment.

For example, if your project configuration looks like this:

.cfg.toml

[options]
install_requires =
    pandas>=0.24.3

[edgetest.envs.pandas_lower]
lower =
    pandas

then edgetest will:

1. Create the pandas_lower virtual environment,

2. Install the local package,

3. Install pandas==0.24.3, and

4. Run the pytest in the environment.

Testing lower bounds of dependencies currently has the following limitations:

• Can only parse main dependencies. Edgetest cannot parse lower bounds specified in extras.

• Can only install lower bounds of packages specified with >=. Edgetest cannot test the lower bounds of packages specified with >.

• Cannot automatically update or export lower bounds of dependencies to a project configuration file.

Note

It is hard to install lower bounds of dependencies if they are very outdated. Older versions of dependencies like pandas may be incompatible with newer Python versions or may not be able to be installed with a given numpy version. In the case where installation is not possible, edgetest will report that the setup was unsuccessful and move on to the next environment.

Using plugins

edgetest is built on a plugin framework that allows for extensibility and modularity (see details here). Below we have listed the plugins that are built and maintained by the edgetest developer team:

Plugin	Description
edgetest-conda	Uses conda or mamba for environment creation instead of venv.
edgetest-hub	Creates a pull request in your GitHub repository with the dependency updates.
edgetest-pip-tools	Refreshes a locked requirements file based on the updated dependency pins.

Note

If you need edgetest to run a different Python version than what is in your current environment you can use edgetest-conda to do so with the python_version configuration.