To set up a dev environment to work on osxphotos code or run tests follow these steps. This assumes you have python 3.7 or later installed. If you need to install python, you can do so with the XCode command lines tools (xcode-select --install) or from python.org.
git clone [email protected]:RhetTbull/osxphotos.gitcd osxphotospython3 -m venv venvsource venv/bin/activatepython3 -m pip install -r dev_requirements.txtpython3 -m pip install -e .
To run the tests, do the following from the main source folder:
python3 -m pytest tests/
- To run a specific test specify its name with the -k flag:
python3 -m pytest -k "test_export_cleanup"
A few tests will look for certain environment variables to determine if they should run.
Some of the export tests rely on photos in my local library and will look for OSXPHOTOS_TEST_EXPORT=1 to determine if they should run.
One test for locale does not run on GitHub's automated workflow and will look for OSXPHOTOS_TEST_LOCALE=1 to determine if it should be run. If you want to run this test, set the environment variable.
Some tests require GPU and will look for OSXPHOTOS_TEST_CONVERT=1. These will be skipped in GitHub Actions CI which doesn't provide a GPU.
A couple of tests require interaction with Photos and configuring a specific test library. Currently these run only on Catalina. The tests must be specified by using a pytest flag. Only one of these interactive tests can be run at a time. The current flags are:
--addalbum: test --add-to-album options (pytest -vv tests/test_photosalbum_unicode.py tests/test_cli_add_to_album.py --addalbum)
--timewarp: test osxphotos timewarp (pytest -vv --timewarp tests/test_cli_timewarp.py tests/test_photodates.py)
--photodates: test osxphotos photodates (pytest -vv --photodates tests/test_photodates.py)
--test-import: test osxphotos import (pytest -vv --test-import tests/test_cli_import.py)
--test-sync: test osxphotos sync (pytest -vv --test-sync tests/test_cli_sync.py)
--test-add-locations: test osxphotos add-locations (pytest -vv --test-add-locations tests/test_cli_add_locations.py)
--test-batch-edit: test osxphotos batch-edit (pytest -vv --test-batch-edit -k batch)
Important: The test code uses several test photo libraries created on various version of MacOS. If you need to inspect one of these or modify one for a test, make a copy of the library (for example, copy it to your ~/Pictures folder) then open the copy in Photos. Once done, copy the revised library back to the tests/ folder. If you do not do this, the Photos background process photoanalysisd will forever try to process the library resulting in updates to the database which will cause git to see changes to the file you didn't intend. I'm not aware of any way to disassociate photoanalysisd from the library once you've opened it in Photos.
Some of the "search_info" tests require data from my personal library on Catalina 10.15.7. The data is generated by running python3 tests/generate_search_info_test_data.py >tests/search_info_test_data_10_15_7.json
There are some utilities in the tests/ folder to generate test data for various tests.
-
tests/generate_sidecars_for_test.py: generate sidecar files for testing. Needs to be run if code is modified that generates sidecar files. This will generate sidecar files in thetests/sidecarsfolder. The sidecar files are used by various tests. -
tests/generate_search_info_test_data.py: generate search_info test data. This is used only by the author to generate test data against my personal photo library. This data is used by the search_info tests. Run aspython3 tests/generate_search_info_test_data.py >tests/search_info_test_data_10_15_7.json -
tests/gen_face_test_data.py: generates face data used test_faceinfo.py -
The file
tests/iphoto_test_data.jsonis used bytest_iphoto.py. It is generated by runningosxphotos query --json --library tests/Test-iPhoto-9.6.1.photolibrary/ > tests/iphoto_test_data.json.- The file must then be edited to replace the full path to the library with
IPHOTO_LIBRARY_ROOT/Test-iPhoto-9.6.1.photolibraryso that it can be used by the tests. This shouldn't be necessary unless changes are made to the test library. - Also, double check if any of the date fields need to be restored back to previous values (example below) found on
tests/iphoto_test_data.jsonso that tests pass.
- The file must then be edited to replace the full path to the library with
"date": "2020-04-12T03:30:23+00:00",
"date_added": "2023-09-27T06:43:07.850189+00:00",
"date_modified": "2023-09-27T06:43:07.885464+00:00",Here's my process for testing any code that manipulates face regions:
Export a test image with one or more face regions using:
osxphotos export ~/Desktop/export --selected --exiftool
Open the exported image in XnViewMP.
In XnViewMP, select View > Show people's region to see the face regions. Verify the face regions are correct.
Then also test the sidecars. Re-export the image without --exiftool but use --sidecar:
osxphotos export ~/Desktop/export --selected --sidecar xmp
Apply the sidecar to the exported image using exiftool:
exiftool -overwrite_original -tagsfromfile ~/Desktop/export/IMG_0001.xmp ~/Desktop/export/IMG_0001.jpg
Re-open the image in XnViewMP and verify the face regions are correct.
Then also test the JSON and exiftool sidecars:
osxphotos export ~/Desktop/export --selected --sidecar json
exiftool -overwrite_original -json=~/Desktop/export/IMG_0001.json ~/Desktop/export/IMG_0001.jpg
Re-open the image in XnViewMP and verify the face regions are correct.
osxphotos export ~/Desktop/export --selected --sidecar exiftool
exiftool -overwrite_original -json=~/Desktop/export/IMG_0001.json ~/Desktop/export/IMG_0001.jpg
Re-open the image in XnViewMP and verify the face regions are correct.
These tests utilize a test Photos library. The test library is populated with photos from flickr and from my own photo library. All images used are licensed under Creative Commons 2.0 Attribution license.
Flickr images used from: