| 1 |
# (C) Copyright 2004-2023 Enthought, Inc., Austin, TX |
| 2 |
# All rights reserved. |
| 3 |
# |
| 4 |
# This software is provided without warranty under the terms of the BSD |
| 5 |
# license included in LICENSE.txt and may be redistributed only under |
| 6 |
# the conditions described in the aforementioned license. The license |
| 7 |
# is also available online at http://www.enthought.com/licenses/BSD.txt |
| 8 |
# |
| 9 |
# Thanks for using Enthought open source! |
| 10 |
|
| 11 |
""" Tests for demo and tutorial examples. |
| 12 |
""" |
| 13 |
|
| 14 |
import contextlib |
| 15 |
import io |
| 16 |
import os |
| 17 |
import sys |
| 18 |
import traceback |
| 19 |
import unittest |
| 20 |
from unittest import mock |
| 21 |
|
| 22 |
import pkg_resources |
| 23 |
from traits.api import HasTraits |
| 24 |
|
| 25 |
from traitsui.tests._tools import ( |
| 26 |
BaseTestMixin, |
| 27 |
is_qt, |
| 28 |
is_qt5, |
| 29 |
is_qt6, |
| 30 |
is_wx, |
| 31 |
process_cascade_events, |
| 32 |
requires_toolkit, |
| 33 |
ToolkitName, |
| 34 |
) |
| 35 |
from traitsui.testing.api import UITester |
| 36 |
|
| 37 |
# This test file is not distributed nor is it in a package. |
| 38 |
HERE = os.path.dirname(__file__) |
| 39 |
|
| 40 |
|
| 41 |
class ExampleSearcher: |
| 42 |
"""This object collects and reports example files to be tested.""" |
| 43 |
|
| 44 |
def __init__(self, source_dirs): |
| 45 |
""" |
| 46 |
Parameters |
| 47 |
---------- |
| 48 |
source_dirs : list of str |
| 49 |
List of directory paths from which Python files will be collected. |
| 50 |
""" |
| 51 |
self.source_dirs = source_dirs |
| 52 |
self.files_may_be_skipped = {} |
| 53 |
|
| 54 |
def skip_file_if(self, filepath, condition, reason): |
| 55 |
"""Mark a file to be skipped for a given condition. |
| 56 |
|
| 57 |
Parameters |
| 58 |
---------- |
| 59 |
filepath : str |
| 60 |
Path of the file which may be skipped from tests. |
| 61 |
condition: callable() -> bool |
| 62 |
The condition for skipping a file. |
| 63 |
reason : str |
| 64 |
Reason for skipping the file. |
| 65 |
""" |
| 66 |
filepath = os.path.abspath(filepath) |
| 67 |
self.files_may_be_skipped[filepath] = (condition, reason) |
| 68 |
|
| 69 |
def is_skipped(self, filepath): |
| 70 |
"""Return if the Python file should be skipped in test. |
| 71 |
|
| 72 |
Parameters |
| 73 |
---------- |
| 74 |
path : str |
| 75 |
Path to a file. |
| 76 |
|
| 77 |
Returns |
| 78 |
------- |
| 79 |
skipped : bool |
| 80 |
True if the file should be skipped. |
| 81 |
reason : str |
| 82 |
Reason why it should be skipped. |
| 83 |
""" |
| 84 |
path = os.path.abspath(filepath) |
| 85 |
if path not in self.files_may_be_skipped: |
| 86 |
return False, "" |
| 87 |
condition, reason = self.files_may_be_skipped[path] |
| 88 |
return condition(), reason |
| 89 |
|
| 90 |
def validate(self): |
| 91 |
"""Validate configuration. Currently this checks all files that may |
| 92 |
be skipped still exist. |
| 93 |
""" |
| 94 |
for filepath in self.files_may_be_skipped: |
| 95 |
if not os.path.exists(filepath): |
| 96 |
raise RuntimeError("{} does not exist.".format(filepath)) |
| 97 |
|
| 98 |
@staticmethod |
| 99 |
def _is_python_file(path): |
| 100 |
"""Return true if the given path is (public) non-test Python file.""" |
| 101 |
_, basename = os.path.split(path) |
| 102 |
_, ext = os.path.splitext(basename) |
| 103 |
return ( |
| 104 |
ext == ".py" |
| 105 |
and not basename.startswith("_") |
| 106 |
and not basename.startswith("test_") |
| 107 |
) |
| 108 |
|
| 109 |
def get_python_files(self): |
| 110 |
"""Report Python files to be tested or to be skipped. |
| 111 |
|
| 112 |
Returns |
| 113 |
------- |
| 114 |
accepted_files : list of str |
| 115 |
Python file paths to be tested. |
| 116 |
skipped_files : (filepath: str, reason: str) |
| 117 |
Skipped files. First item is the file path, second |
| 118 |
item is the reason why it is skipped. |
| 119 |
""" |
| 120 |
accepted_files = [] |
| 121 |
skipped_files = [] |
| 122 |
for source_dir in self.source_dirs: |
| 123 |
for root, _, files in os.walk(source_dir): |
| 124 |
for filename in files: |
| 125 |
path = os.path.abspath(os.path.join(root, filename)) |
| 126 |
if not self._is_python_file(path): |
| 127 |
continue |
| 128 |
|
| 129 |
skipped, reason = self.is_skipped(path) |
| 130 |
if skipped: |
| 131 |
skipped_files.append((path, reason)) |
| 132 |
else: |
| 133 |
accepted_files.append(path) |
| 134 |
|
| 135 |
# Avoid arbitrary ordering from the OS |
| 136 |
return sorted(accepted_files), sorted(skipped_files) |
| 137 |
|
| 138 |
|
| 139 |
# ============================================================================= |
| 140 |
# Configuration |
| 141 |
# ============================================================================= |
| 142 |
|
| 143 |
# Tutorial files are not part of the package data |
| 144 |
TUTORIALS = os.path.join( |
| 145 |
HERE, |
| 146 |
"..", |
| 147 |
"examples", |
| 148 |
"tutorials", |
| 149 |
"doc_examples", |
| 150 |
"examples", |
| 151 |
) |
| 152 |
|
| 153 |
# Demo files are part of the package data. |
| 154 |
DEMO = pkg_resources.resource_filename("traitsui", "examples/demo") |
| 155 |
|
| 156 |
#: Explicitly include folders from which example files should be found |
| 157 |
#: recursively. |
| 158 |
SOURCE_DIRS = [ |
| 159 |
DEMO, |
| 160 |
TUTORIALS, |
| 161 |
] |
| 162 |
|
| 163 |
SEARCHER = ExampleSearcher(source_dirs=SOURCE_DIRS) |
| 164 |
SEARCHER.skip_file_if( |
| 165 |
os.path.join(DEMO, "Advanced", "HDF5_tree_demo.py"), |
| 166 |
lambda: sys.platform == "darwin", |
| 167 |
"This example depends on PyTables which may be built to require CPUs with " |
| 168 |
"a specific AVX version that is not supported on a paricular OSX host.", |
| 169 |
) |
| 170 |
SEARCHER.skip_file_if( |
| 171 |
os.path.join(DEMO, "Advanced", "Table_editor_with_progress_column.py"), |
| 172 |
is_wx, |
| 173 |
"ProgressRenderer is not implemented in wx.", |
| 174 |
) |
| 175 |
SEARCHER.skip_file_if( |
| 176 |
os.path.join(DEMO, "Advanced", "Scrubber_editor_demo.py"), |
| 177 |
is_qt, |
| 178 |
"ScrubberEditor is not implemented in qt.", |
| 179 |
) |
| 180 |
SEARCHER.skip_file_if( |
| 181 |
os.path.join(DEMO, "Extras", "animated_GIF.py"), |
| 182 |
lambda: not is_wx(), |
| 183 |
"Only support wx", |
| 184 |
) |
| 185 |
SEARCHER.skip_file_if( |
| 186 |
os.path.join(DEMO, "Extras", "Tree_editor_with_TreeNodeRenderer.py"), |
| 187 |
lambda: not is_qt(), |
| 188 |
"Only support Qt", |
| 189 |
) |
| 190 |
SEARCHER.skip_file_if( |
| 191 |
os.path.join(DEMO, "Extras", "windows", "flash.py"), |
| 192 |
lambda: not is_wx(), |
| 193 |
"Only support wx", |
| 194 |
) |
| 195 |
SEARCHER.skip_file_if( |
| 196 |
os.path.join(DEMO, "Extras", "windows", "internet_explorer.py"), |
| 197 |
lambda: not is_wx(), |
| 198 |
"Only support wx", |
| 199 |
) |
| 200 |
SEARCHER.skip_file_if( |
| 201 |
os.path.join(TUTORIALS, "view_multi_object.py"), |
| 202 |
lambda: True, |
| 203 |
"Require wx and is blocking.", |
| 204 |
) |
| 205 |
SEARCHER.skip_file_if( |
| 206 |
os.path.join(TUTORIALS, "view_standalone.py"), |
| 207 |
lambda: True, |
| 208 |
"Require wx and is blocking.", |
| 209 |
) |
| 210 |
|
| 211 |
# Validate configuration. |
| 212 |
SEARCHER.validate() |
| 213 |
|
| 214 |
|
| 215 |
# ============================================================================= |
| 216 |
# Test run utility functions |
| 217 |
# ============================================================================= |
| 218 |
|
| 219 |
|
| 220 |
def replaced_configure_traits( |
| 221 |
instance, |
| 222 |
filename=None, |
| 223 |
view=None, |
| 224 |
kind=None, |
| 225 |
edit=True, |
| 226 |
context=None, |
| 227 |
handler=None, |
| 228 |
id="", |
| 229 |
scrollable=None, |
| 230 |
**args, |
| 231 |
): |
| 232 |
"""Mocked configure_traits to launch then close the GUI.""" |
| 233 |
ui_kwargs = dict( |
| 234 |
view=view, |
| 235 |
parent=None, |
| 236 |
kind="live", # other options may block the test |
| 237 |
context=context, |
| 238 |
handler=handler, |
| 239 |
id=id, |
| 240 |
scrollable=scrollable, |
| 241 |
**args, |
| 242 |
) |
| 243 |
with UITester().create_ui(instance, ui_kwargs): |
| 244 |
pass |
| 245 |
|
| 246 |
|
| 247 |
@contextlib.contextmanager |
| 248 |
def replace_configure_traits(): |
| 249 |
"""Context manager to temporarily replace HasTraits.configure_traits |
| 250 |
with a mocked version such that GUI launched are closed soon after they |
| 251 |
are open. |
| 252 |
""" |
| 253 |
original_func = HasTraits.configure_traits |
| 254 |
HasTraits.configure_traits = replaced_configure_traits |
| 255 |
try: |
| 256 |
yield |
| 257 |
finally: |
| 258 |
HasTraits.configure_traits = original_func |
| 259 |
|
| 260 |
|
| 261 |
def run_file(file_path): |
| 262 |
"""Execute a given Python file. |
| 263 |
|
| 264 |
Parameters |
| 265 |
---------- |
| 266 |
file_path : str |
| 267 |
File path to be tested. |
| 268 |
""" |
| 269 |
with open(file_path, "r", encoding="utf-8") as f: |
| 270 |
content = f.read() |
| 271 |
|
| 272 |
globals = { |
| 273 |
"__name__": "__main__", |
| 274 |
"__file__": file_path, |
| 275 |
} |
| 276 |
with replace_configure_traits(), mock.patch( |
| 277 |
"sys.stdout", new_callable=io.StringIO |
| 278 |
), mock.patch("sys.argv", [file_path]): |
| 279 |
# Mock stdout: Examples typically print educational information. |
| 280 |
# They are expected but they should not pollute test output. |
| 281 |
# Mock argv: Some example reads sys.argv to allow more arguments |
| 282 |
# But all examples should support being run without additional |
| 283 |
# arguments. |
| 284 |
exec(content, globals) |
| 285 |
|
| 286 |
|
| 287 |
# ============================================================================= |
| 288 |
# load_tests protocol for unittest discover |
| 289 |
# ============================================================================= |
| 290 |
|
| 291 |
|
| 292 |
def load_tests(loader, tests, pattern): |
| 293 |
"""Implement load_tests protocol so that when unittest discover is run |
| 294 |
with this test module, the tests in the demo folder (not a package) are |
| 295 |
also loaded. |
| 296 |
|
| 297 |
See unittest documentation on load_tests |
| 298 |
""" |
| 299 |
# Keep all the other loaded tests. |
| 300 |
suite = unittest.TestSuite() |
| 301 |
suite.addTests(tests) |
| 302 |
|
| 303 |
# Expand the test suite with tests from the examples, assuming |
| 304 |
# the test for ``group/script.py`` is placed in ``group/tests/`` directory. |
| 305 |
accepted_files, _ = SEARCHER.get_python_files() |
| 306 |
test_dirs = set( |
| 307 |
os.path.join(os.path.dirname(path), "tests") for path in accepted_files |
| 308 |
) |
| 309 |
test_dirs = set(path for path in test_dirs if os.path.exists(path)) |
| 310 |
for dirpath in sorted(test_dirs): |
| 311 |
|
| 312 |
# Test files are scripts too and they demonstrate running the |
| 313 |
# tests. Mock the run side-effect when we load the test cases. |
| 314 |
with mock.patch.object(unittest.TextTestRunner, "run"): |
| 315 |
test_suite = unittest.TestLoader().discover( |
| 316 |
dirpath, pattern=pattern |
| 317 |
) |
| 318 |
if is_qt() or is_wx(): |
| 319 |
suite.addTests(test_suite) |
| 320 |
|
| 321 |
return suite |
| 322 |
|
| 323 |
|
| 324 |
# ============================================================================= |
| 325 |
# Test cases |
| 326 |
# ============================================================================= |
| 327 |
|
| 328 |
|
| 329 |
@requires_toolkit([ToolkitName.qt, ToolkitName.wx]) |
| 330 |
class TestExample(BaseTestMixin, unittest.TestCase): |
| 331 |
def setUp(self): |
| 332 |
BaseTestMixin.setUp(self) |
| 333 |
|
| 334 |
def tearDown(self): |
| 335 |
BaseTestMixin.tearDown(self) |
| 336 |
|
| 337 |
def test_run(self): |
| 338 |
accepted_files, skipped_files = SEARCHER.get_python_files() |
| 339 |
|
| 340 |
for file_path in accepted_files: |
| 341 |
with self.subTest(file_path=file_path): |
| 342 |
try: |
| 343 |
run_file(file_path) |
| 344 |
except Exception as exc: |
| 345 |
message = "".join( |
| 346 |
traceback.format_exception(*sys.exc_info()) |
| 347 |
) |
| 348 |
self.fail( |
| 349 |
"Executing {} failed with exception {}\n {}".format( |
| 350 |
file_path, exc, message |
| 351 |
) |
| 352 |
) |
| 353 |
finally: |
| 354 |
# Whatever failure, always flush the GUI event queue |
| 355 |
# before running the next one. |
| 356 |
process_cascade_events() |
| 357 |
|
| 358 |
# Report skipped files |
| 359 |
for file_path, reason in skipped_files: |
| 360 |
with self.subTest(file_path=file_path): |
| 361 |
# make up for unittest not reporting the parameter in skip |
| 362 |
# message. |
| 363 |
raise unittest.SkipTest( |
| 364 |
"{reason} (File: {file_path})".format( |
| 365 |
reason=reason, file_path=file_path |
| 366 |
) |
| 367 |
) |