Package: pytest-datafiles
pytestplugin to create atmp_pathcontaining a preconfigured set of
files and/or directories.Note about maintenance:This project is maintained and bug reports or pull
requests will be addressed. There is little activity because it simply works and
no changes are required.FeaturesThis plugin allows you to specify one or several files/directories that are
copied to a temporary directory (tmp_path) before the execution of the test.
This means the original files are not modified and every test runs on its own
version of the same files.Files/directories can be specified either asstringsor aspathlib.Pathobjects.To take advantage of thedatafilesfixture in a test function, adddatafilesas one of the test function parameters (per usual withpytestfixtures) and decorate the test function with@pytest.mark.datafiles(file1,
file2, dir1, dir2, …). See the examples below.Thedatafilesvariable in your test function is a pathlib.Path object
(tmp_path) where the copied files are located. Under Linux systems this
will most likely be some subdirectory of/tmp/.OptionsThe following options can be specified as keyword arguments (kwargs) to the@pytest.mark.datafilesdecorator function:keep_top_dir:For all parameters that represent directories, keep that
directory instead of only (recursively) copying its content. Possible values
areTrueorFalse.Falseis the default value.on_duplicate:Specify the action to take when duplicate files/directories
are found. Possible values are:exception,ignoreandreplace. The
default value isexception.exception:An exception is raised instead of copying the duplicate
file/directory.ignore:The second (or subsequent) files/directories with the same name
as the first one are simply ignored (i.e., the first file/directory with the
duplicate name is kept).replace:The second (or subsequent) files/directories with the same name
replace the previous ones (i.e., the last file/directory with the duplicate
name is kept).See below for someexamples.Installationpipinstallpytest-datafilesUpgrade to 3.0Version 3 now usestmp_path, resulting inpathlib.Pathobjects
instead ofpy.path.Your tests may need to be adjusted. Inexamples/example_upgradev3.pyyou see some possible
variations.UsageThe full code with more details for the examples can be found inexamples/.Example 1One possible use case is when you are running tests on very big files that are
not included or packaged with your tests. For example, your test files are
large video files stored under/opt/big_files/. You don’t want your tests modifying
the original files, but the files are required by the tests. You can reference these
data files in your test method as follows:# more details in `examples/example_1.py`@pytest.mark.datafiles('/opt/big_files/film1.mp4')deftest_fast_forward(datafiles):# ...Example 2Now for another use case: let’s say in the directory where your tests are located, you
place a directory namedtest_files. Here you have a lot of images you want to run tests
on. By using this plugin, you make sure the original files undertest_filesare not
modified by every test.# more details in `examples/example_2.py`@pytest.mark.datafiles(FIXTURE_DIR/'img1.jpg',FIXTURE_DIR/'img2.jpg',FIXTURE_DIR/'img3.jpg',)deftest_find_borders(datafiles):# ...Example 3If all (or many) of your tests rely on the same files it can be easier to
define one decorator beforehand and apply it to every test like this example:# more details in `examples/example_3.py`ALL_IMGS=pytest.mark.datafiles(FIXTURE_DIR/'img1.jpg',FIXTURE_DIR/'img2.jpg',FIXTURE_DIR/'img3.jpg',)@ALL_IMGSdeftest_something1(datafiles):# ...Example 4Imagine you have 3 directories (dir1,dir2,dir3) each containing the files
(fileAandfileB).This example clarifies the optionson_duplicateandkeep_top_dir.Example 5You can also use a str paths.# more details in `examples/example_5.py`@pytest.mark.datafiles(os.path.join(FIXTURE_DIR,'img1.jpg'),os.path.join(FIXTURE_DIR,'img2.jpg'),os.path.join(FIXTURE_DIR,'img3.jpg'),)deftest_str(datafiles):# ...ContributingContributions are very welcome. Tests can be run withtox. Please
ensure the coverage stays at least the same before you submit a pull
request.To create and upload a new package first update the version number and then:pip3install--user-Utwinemakecleanmakedisttwineupload--repository-urlhttps://test.pypi.org/legacy/dist/*# Verify the package is usablevirtualenv-ppython3test-venvtest-venv/bin/pipinstallpytesttest-venv/bin/pipinstall--index-urlhttps://test.pypi.org/simple/pytest-datafiles# Create some test_example.py (e.g. with one of the examples above)test-venv/bin/pytesttest_example.py# Set the git tag for final releasegittag-a3.0gitpush--tags# Upload the package for final releasetwineuploaddist/*Finally create a release on GitHub and add the packages from dist/* to it.Of course this will only work if you have the necessary PyPI credentials for
this package.LicenseDistributed under the terms of theMIT license, “pytest-datafiles” is
free and open source software.IssuesIf you encounter any problems, pleasefile an issuealong with a
detailed description.AcknowledgementsThanks to@flubfor the idea to usepytestmarks to solve the
problem this plugin is trying to solve.Some ideas to improve this project were taken from theCookiecuttertemplatescookiecutter-pypackageandcookiecutter-pytest-plugin.Change LogAll notable changes to this project will be documented in this file.
This project adheres toSemantic Versioning. The change log is
formatted as suggested byKeep a CHANGELOG.UnreleasedAdded
Changed
Deprecated
Removed
Fixed
Security3.0ChangedBREAKING CHANGE: Usingpathlib.Pathinstead ofpy.path(#7)BREAKING CHANGE: Removed support for Python 2.7 and Python 3 <= 3.62.0.1FixedRegister custom marker ‘datafiles’ to avoid PytestUnknownMarkWarning
(#18)2.0AddedExplicit support for Python 3.6 (no changes were necessary)RemovedBREAKING CHANGE: Python 2.6 is no longer supported (because we rely on pytest
>= 3.6)FixedUse the new pytest mark API to fix MarkInfo warnings (#2)BREAKING CHANGE: Symlinks are now copied as links instead of copying the
target they point to (#1)1.0ChangedBump version to 1.0 to signal that the plugin is stableMinor refactorization without repercussions for usersOnly use regular ‘paths’ (str) instead of py.path objects in documentation
examples because they were confusing to some people (unfamiliar with py.path)0.2AddedSupport for directoriesOption ‘keep_top_dir’ to keep the top level directory (instead of only
copying its content). Possible values are: True, False (default)Option ‘on_duplicate’ to specify what to do when duplicate files or
directories are encountered. Possible values are: ‘exception’ (default),
‘ignore’, ‘overwrite’0.1AddedSpecify one or multiple files to be copied by decorating the test
function