{"id":20215224,"url":"https://github.com/kitwaremedical/slicerpythontestrunner","last_synced_at":"2025-04-10T14:11:07.772Z","repository":{"id":217306708,"uuid":"743517683","full_name":"KitwareMedical/SlicerPythonTestRunner","owner":"KitwareMedical","description":"Python test runner extension for 3D Slicer based on PyTest and PyTest JSON Report","archived":false,"fork":false,"pushed_at":"2025-03-27T13:25:38.000Z","size":860,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-27T14:28:48.731Z","etag":null,"topics":["3d-slicer-extension"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KitwareMedical.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-15T12:08:01.000Z","updated_at":"2025-03-27T13:25:32.000Z","dependencies_parsed_at":"2024-04-23T07:35:40.301Z","dependency_job_id":"ba6eda9c-7723-462d-9c83-20c7199de0de","html_url":"https://github.com/KitwareMedical/SlicerPythonTestRunner","commit_stats":null,"previous_names":["kitwaremedical/slicerpythontestrunner"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitwareMedical%2FSlicerPythonTestRunner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitwareMedical%2FSlicerPythonTestRunner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitwareMedical%2FSlicerPythonTestRunner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KitwareMedical%2FSlicerPythonTestRunner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KitwareMedical","download_url":"https://codeload.github.com/KitwareMedical/SlicerPythonTestRunner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248232418,"owners_count":21069487,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-slicer-extension"],"created_at":"2024-11-14T06:20:35.284Z","updated_at":"2025-04-10T14:11:07.765Z","avatar_url":"https://github.com/KitwareMedical.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Slicer Python Test Runner\n\n\u003cdiv style=\"text-align: center;\"\u003e\n\u003cimg src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/SlicerPythonTestRunner.png\"/\u003e\n\u003c/div\u003e\n\n## Table of contents\n\n* [Introduction](#introduction)\n* [Why this extension](#why-this-extension)\n* [Using the extension](#using-the-extension)\n* [Test decorators](#test-decorators)\n* [Changelog](#changelog)\n* [Contributing](#contributing)\n\n## Introduction\n\n\u003cimg src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/0.png\"/\u003e\n\nThis module allows running 3D Slicer module's unit tests directly from 3D Slicer's UI.\n\nIt uses PyTest and PyTest JSON Report to discover the unit tests in a given directory or file and runs the tests in a\nseparate 3D Slicer process.\n\nAfter the tests have been run, the results are displayed in the UI.\nThe plugin also provides decorators to help running unit tests directly in your favorite IDEs.\n\n## Why this extension\n\n3D Slicer is a C++ based application and provides numerous libraries which are conveniently wrapped and available in\nits Python environment.\n\nThe Python interpreter is named `python-real` in Slicer's binary folder and can be used directly to run Python libraries\ninstalled in the Python environment such as NumPy and ITK.\n\nSome features, however, are only available when running inside the full 3D Slicer environment, for instance access to\nthe application main window or accessing loaded modules.\n\nWhen testing a 3D Slicer modules, it is hence necessary to run in the full 3D Slicer environment.\n\n3D Slicer provides a `Reload and Test` developer tool which reloads the current module python file and runs its unit\ntests. However, this mechanism has the following limitations :\n\n* Due to Python's lack of reloading mechanism for packages, it only works well for single file modules\n* The tests run only provides print in Slicer's console\n* The test run doesn't allow for filtering tests to run\n\n3D Slicer also has CTest testing functionalities. However, these functionalities are not readily available for\na developer wishing to develop a Slicer extension using a pre-built application.\n\nBy launching a new Slicer process for its tests and using PyTest's filtering mechanism, this extension provides an\nefficient way of running UnitTests inside 3D Slicer without the previous caveats.\n\n## Using the extension\n\nThis extension can be installed directly using Slicer's extension manager.\n\nOnce installed, navigate to `Developer Tools\u003eSlicer Python Test Runner` in the modules drop down menu or search directly\nfor `Slicer Python Test Runner`.\n\nYou will see the following, empty, test runner module:\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/1.png\"/\u003e\n\nStart by selecting the directory containing the tests using the top path selector.\nThen enter the file filter pattern, and name filter pattern.\n`Note`: The function filter will be applied when running the tests but not during test collection.\n\n*Warning* : Note that by default, the module uses PyTest's conventions which expects test files, classes and functions\nto be prefixed by `test`.\n\nIf you are testing using 3D Slicer convention, please use the following pattern:\n\n* file : *.py\n\nClick on the `collect` button to check that the tests to run are correctly found by the extension.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/3.png\"/\u003e\n\nAfterwards, click on the `run` button to start testing.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/4.png\"/\u003e\n\nYou can run the tests in parallel by clicking on the `run in parallel` button.\nThe run in parallel will start one Slice instance per test file found in the test directory.\nThe maximum number of instance run in parallel can be controlled in the settings dialog.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/13.png\"/\u003e\n\nYou can cancel test running using the `stop` button. Note however that as the test runner starts new Slicer processes\nthe cancel may not be graceful and 3D Slicer windows may have to be killed manually.\n\nOnce the tests have run, you will see the tests results in the UI.\n\nClicking on one test in the tree view will display its result in the text editor below, along the error if any.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/5.png\"/\u003e\n\nAdditional buttons allow to filter the tests displayed in the UI (passed, ignored, collected).\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/6.png\"/\u003e\n\nTo modify the execution settings, click on the `settings` button.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/7.png\"/\u003e\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/8.png\"/\u003e\n\nThe following settings are accessible:\n\n* Close Slicer after run: Closes the spawned Slicer process when the tests have finished running.\n* Use main window: If unchecked, opens the Slicer process without any main window GUI\n* Minimize main window: If checked and a main window is used, minimizes the launched window at startup\n* Max Slicer instances: When the Run files independently option is checked, defines the maximum number of concurrent 3D\n  Slicer instances\n* Extra slicer args: Comma separated list of args to use when starting Slicer instance (refer to Slicer launcher CLI\n  args for more info)\n* Extra pytest args: Comma separated list of args to pass to PyTest (please refer to PyTest args for more info)\n* Run test coverage: If checked, test coverage will be executed on the tests which are ran\n* Coverage report format: Comma separated list of coverage formats. For now only one format should be used from the UI.\n  If you want to output more coverage files, it is recommended to use coverage settings file in your project.\n* Coverage source: Comma separated list of sources folders to include in the coverage report.\n* Coverage path: Output file or directory path where the coverage report will be put.\n\nThe test module is also compatible with `pytest.ini` and `.coveragerc` settings files.\nIt should also be compatible with other settings files in your project to ease the configuration process.\n\n## Running tests in parallel\n\nWhen running tests in parallel, it may be interesting to generate independent files or artefacts.\nTo simplify this process, two keywords are provided to generate artefact names :\n\n* timestamp : Run time stamp with format \"%Y-%m-%d_%H-%M-%S.%f\"\n* filename_suffix : Coverage like file name suffix with machine_name.process_id.random_number format\n\nThese values can be used by using Python's string format syntax in the pytest args line edit :\n\n* --html=report_{filename_suffix}_{timestamp}.html : This option will generate an html report with both filename suffix\n  and timestamp. *Note:* Both Junit XML and pytest-html output formats are supported out of the box by the export\n  functionality.\n\n## Exporting the test results\n\nThe tests results can be saved by clicking on the save button.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/10.png\"/\u003e\n\nThe button will open a dialog to select the output file.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/11.png\"/\u003e\n\nThe following formats are supported :\n\n* xml: The output will be saved as JUNIT xml format\n* html: The output will be saved using pytest-html and pytest-html-merger\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/12.png\"/\u003e\n\n## Test decorators\n\nThis module also provides the following decorators :\n\n* runTestInSlicerContext: This decorator will run the current test by using the Module's test runner if executed\n  outside a 3D Slicer application. This allows to run the tests directly in your favorite IDE's test runner.\n* skipTestOutsideSlicer: This decorator will skip the current test if executed outside a 3D Slicer application.\n\n\u003cimg class=\"center\" src=\"https://github.com/KitwareMedical/SlicerPythonTestRunner/raw/main/Screenshots/9.png\"/\u003e\n\n## Changelog\n\n### v1.1.0\n\n* Add support for parallel test execution and test coverage\n* Add result export in JUnit XML and HTML formats\n* Add support for pytest args file name suffixes\n\n## Contributing\n\nThis project welcomes contributions. If you want more information about how you can contribute, please refer to\nthe [CONTRIBUTING.md file](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitwaremedical%2Fslicerpythontestrunner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitwaremedical%2Fslicerpythontestrunner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitwaremedical%2Fslicerpythontestrunner/lists"}