Development practices for cogent3

Several GitHub workflows have been implemented for testing and reformatting code changes. These are triggered for each submitted PR and all workflows must pass before the changes are incorporated in the main repo.

However, we recommend you conduct these checks regularly (locally) as you develop.

Table of contents:

• How to run unit tests
• Formatting code (linting)
• Keeping your feature branch updated

How to run unit tests

Tests should be run regularly as you develop, particularly with the test module relevant to the issue you are working on. cogent3 utilises pytest for unit testing.

Running specifc test modules

When developing, you may only want to run the test modules, for example, relevant to the function you are modifying:

$ cd Cogent3/tests
$ pytest test_util test_phylo.py test_recalculation.py test_format/

This will run all the test methods within test_phylo.py, test_recalculation.py and the methods within the files in the test_format/ directory.

When all unit tests passes, the output should look something like the below, where each . represents a single test method:

============ test session starts =============
[some information about your setup]
collected 31 items

test_phylo.py ..................       [ 58%]
test_recalculation.py .                [ 61%]
test_format/test_bedgraph.py ........  [ 87%]
test_format/test_clustal.py ...        [ 96%]
test_format/test_fasta.py .            [100%]

============= 31 passed in 0.37s =============

Running a single test method

To test one method in a file:

$ pytest -k test_union_value_dict

For other useful ways to use pytest and control the output, see:

• How to invoke pytest
• Managing pytest's output

Automating tests across multiple Python environments

nox is used to automate testing in specific, or multiple, python environments.

Note: nox must always be run in the (forked) cogent3 repo.

To view the different test sessions available, run nox --list. The options should look like:

* test_slow-3.8
* test_slow-3.9
* test_slow-3.10
* test_slow-3.11
* test-3.8
* test-3.9
* test-3.10
* test-3.11
* testmpi-3.8
* testmpi-3.9
* testmpi-3.10
* testmpi-3.11
* testdocs-3.8
* testdocs-3.9
* testdocs-3.10
* testdocs-3.11

How to run a test session

To run all unit tests under python 3.10:

cd path_to_cogent3
nox -s test-3.10

This is the same as running:

cd path_to_Cogent3/tests
pytest

The test suite can be completed faster by running them in parallel with the pytest-xdist plugin. To distribute jobs to the available number of CPUs:

pytest -n auto

Formatting code (linting)

cogent3 uses ruff for code formatting.

These tools should be run after making changes to the code, and before you are ready to commit.

cd Cogent3/
ruff check --select I --fix . && ruff format .

Updating the documentation

After making changes to the code, ensure that the documentation is updated with the relevant changes (if required).

See Contributing documentation.

Keeping your feature branch updated

You should aim to keep your fork up-to-date with the cogent3/develop branch as you develop. You should also ensure that your fork is up-to-date before submitting a PR.

Note: Ensure that you have configured the upstream branch.

$ git fetch upstream
$ git checkout feature/issue-<ISSUE_NUMBER>
$ git rebase upstream/develop

References:

• Rebasing on main (NumPy)
• #42 Recommended way of updating forked origin with remote

---

↩️ Back to The development workflow