Development Instructions
ConSeqUMI was developed using Test-Driven Development (TDD) and is formatted via Black, the python code formatter. Any additions to ConSeqUMI are expected to have valid tests made and tested along with all previous tests and to run through Black before being accepted into the main branch.
For a more layman description of the value and benefits of TDD, it is recommended you look at this Uncle Bob video. This is perhaps one of the best introductions you will find to TDD.
Tests were written to be run with PyTest. It can be installed with pip.
-
Activate the necessary environments to run ConSeqUMI. You will find instructions for this in section 3 of the installation instructions.
-
Enter the following code.
pip install pytest
ConSeqUMI has all tests in the tests directory of the repository. Using the pytest command in a directory will automatically search through every subdirectory for python files that start with _test. It will then run every function in those files that similarly starts with test_ and provide a final pass/fail summary of all tests. You will notice that the structure of the tests directory largely mirrors the structure of the src/ConSeqUMI/ directory. This is intentional. You will find the tests for a particular file in the same structure location in the tests directory.
For instance, let's say you want to determine which tests were made for the following file.
src/ConSeqUMI/consensus/consensus.py
You will find the tests in the mirrored file in the tests directory here.
tests/consensus/test_consensus.py
To run PyTest, enter the tests directory from the command line. Then run pytest.
cd <path-to-ConSeqUMI>/tests
pytest
The output should look something like the following. Note that some of the tests are dependent on the existence of specific executables, like lamassemble and medaka. If those executables are not present, those tests will be skipped.
There are also instances where a test case was not written because it was unclear how to write one. In those instances, placeholder unit tests were placed in their respective files but are explicitly skipped, as can be seen in the above output.
In effect, every time an addition is made to the code, a new test case should be made in conjunction with that update and confirmed to work with all the others. Furthermore, even after changes to the code that do not affect the output (refactoring etc.), the tests should be run - that will let you know if any changes accidentally introduced bugs that impact the efficacy of the program.
There are many ways to write code. Some ways are more standardized than others, and following those standard practices can make your code more readable in the future. To do this, we used Black. It is recommended you read the documentation and examples provided in the Black repository linked at the top of this wiki page.
-
Activate the necessary environments to run ConSeqUMI. You will find instructions for this in section 3 of the installation instructions.
-
Enter the following code.
pip install black
To run Black, enter the ConSeqUMI root directory.
cd <path-to-ConSeqUMI>
black .
Black will automatically format all python files. This will not change their functionality in any way. If it does (run your tests and make sure it's still working), you can make an issue on their github repository linked at the top of this wiki page.