Running the unit tests#
Lightkurve has many unit tests which check that our basic functionality works as we expect. Before we can make any changes to Lightkurve we have to check that these tests all pass. If you open a pull request to Lightkurve, these tests will be run automatically. If they pass, your code can be reviewed and potentially merged into the Lightkurve main branch.
However, running these tests online can take a long time. Running the tests locally on your machine is much faster, and will let you check that your work still maintains the expected Lightkurve behavior as you develop your code.
How do I run tests locally?#
Lightkurve uses pytest for testing. You should have a local development environment created. See our guide on on Installing the development environment.
First off, you need to find the directory that your Lightkurve installation is in. You can check this by looking at the Lightkurve path:
import lightkurve as lk
print(lk.__path__)
In a terminal, cd into the Lightkurve directory. Yours should look something like this:
Note that here we’re using the main branch. If you want to run the tests on a branch you are developing, switch to that branch using git checkout branchname. Once you’re in the lightkurve directory, go to the tests directory in lightkurve/tests.
In this directory you should find several tests labeled test_xxx.py. You can run a test using pytest. For example, to test the lightkurve.targetpixelfile module you would execute:
poetry run pytest test_targetpixelfile.py
If the tests are successful, you should see a green success message such as
Why are some of the tests marked “s”/ Why are some tests skipped?#
Running some of our tests requires external data, e.g. some require data to be downloaded from MAST. These tests take a little longer, so we skip them by default. To run all the tests simply use:
poetry run pytest test_targetpixelfile.py --remote-data
Note
To speed up the tests, you can instruct the tests use a specific directory for data file cache, so that when the tests are re-run, data files in the local directory will be used, instead of being downloaded over the network.
Specify the data file cache directory via XDG_CACHE_HOME environment variable. For example,
$ XDG_CACHE_HOME=/my_dev/lk-test-cache poetry run pytest test_targetpixelfile.py --remote-data
The data files will be cached at /my_dev/lk-test-cache/lightkurve in the above example.
My tests passed, but I got warning messages#
Sometimes you will get warnings in your tests, causing your result to be yellow instead of green. For example, you may get an output that looks like this:
While this is not ideal, some Lightkurve tests do raise warnings currently. This will become less and less likely as Lightkurve improves.
My tests failed#
If your test fails, don’t worry, this is what tests are for. Take a look at the traceback that pytest provides for you. If your test has failed then you will see an F next to the test you’ve run, for example:
Underneath, you will then see the traceback of the test that failed. For example, the traceback below shows that there is an AssertionError.
In the test, we have made an assertion
assert_array_equal(lc_add.flux, lc.flux + 2).
However in the traceback we can see that these two arrays are not actually equal, and so the test is breaking.
Use this information to correct the code you’re developing until the tests pass. In rare cases (such as the case above) it is the test itself that is incorrect, not the lightkurve code. If you believe there is an error in one of the tests, point it out in your PR for everyone to comment and discuss.
When should I run tests?#
Before you open a PR to Lightkurve, ideally you should run these tests locally and check that they are all passing. If they aren’t passing, and you are confused as to why they are not, you can open a PR and ask for help.
Can I write my own test?#
Ideally, any PR opened to Lightkurve with new functionality should include some tests. These tests check that the basic functionality of your PR works. That way, if in the future, people create new features that break your PR, we will be alerted. Read through the pytest documentation and take a look at our existing tests to get an idea of how to write your own.
I can’t run any tests.#
We run our unit tests using pytest. This should have been installed when you installed Lightkurve. However, if your tests don’t run, you may want to check all the test dependencies are installed. See our guide on on Installing the development environment.
How to generate an HTML report?#
Use pytest-html extension. Install it by:
python -m pip install pytest-html
or in conda:
conda install pytest-html
Then you can generate an HTML report. For example:
poetry run pytest --html=build/tests/report.html test_targetpixelfile.py