tkintertester 0.1.0__tar.gz

tkintertester-0.1.0/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

tkintertester-0.1.0/PKG-INFO

@@ -0,0 +1,323 @@
+Metadata-Version: 2.4
+Name: tkintertester
+Version: 0.1.0
+Summary: A minimal, event-loop-native test harness for Tkinter GUI applications
+Author: Lion Kimbro
+License-Expression: CC0-1.0
+Project-URL: Repository, https://github.com/LionKimbro/tkintertester
+Keywords: tkinter,testing,gui,test-harness
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# tkintertester
+
+A minimal, event-loop-native test harness for Tkinter GUI applications.
+
+## The Problem
+
+Tkinter doesn't play well with traditional testing approaches:
+
+1. **Tk can't restart cleanly.** Once you destroy a Tk root and try to create another in the same process, things break. This makes pytest/unittest fixtures that create and tear down Tk windows unreliable or impossible.
+
+2. **Tk runs a blocking event loop.** You can't just "call" your GUI from test code and inspect it—that blocks the mainloop or requires threading/async complexity.
+
+3. **Tk silently swallows exceptions.** Exceptions in callbacks get printed to stderr but don't propagate—your test keeps running even though something failed.
+
+## The Solution
+
+Run tests *inside* the Tk event loop itself.
+
+- One process, one thread, one `mainloop()`
+- Tests execute as sequences of **step functions** scheduled via `root.after()`
+- Step functions return control immediately—they never block
+- The harness manages test progression, timeouts, and results
+- Exceptions in callbacks are caught and fail the current test
+
+## Design Principles
+
+- **No async/await** — step-based execution driven by return values
+- **No classes** — global functions and dictionaries
+- **No simulation** — tests run in the real Tk event loop
+- **Lightweight harness** — doesn't own or track your widgets
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Example
+
+```python
+import tkinter
+from tkinter import ttk
+from tkintertester import harness
+
+# Application state
+app = {"count": 0, "toplevel": None}
+widgets = {}
+
+def entry():
+    """Set up the app."""
+    app["count"] = 0
+    app["toplevel"] = tkinter.Toplevel(harness.g["root"])
+    widgets["label"] = ttk.Label(app["toplevel"], text="0")
+    widgets["label"].grid(row=0, column=0)
+    widgets["button"] = ttk.Button(
+        app["toplevel"], text="+1",
+        command=lambda: increment()
+    )
+    widgets["button"].grid(row=1, column=0)
+
+def reset():
+    """Reset between tests."""
+    app["toplevel"].destroy()
+    widgets.clear()
+
+def increment():
+    app["count"] += 1
+    widgets["label"].config(text=str(app["count"]))
+
+# Define a test
+def test_increment():
+    def step_click():
+        widgets["button"].invoke()
+        return ("next", None)
+
+    def step_verify():
+        if widgets["label"].cget("text") == "1":
+            return ("success", None)
+        return ("fail", "Counter should be 1")
+
+    return [step_click, step_verify]
+
+# Run
+harness.add_test("Increment counter", test_increment())
+harness.set_resetfn(reset)
+harness.set_timeout(5000)
+harness.run_host(entry, flags="x")
+harness.print_results()
+```
+
+## API Reference
+
+### Test Registration
+
+```python
+harness.add_test(title, steps)
+```
+Register a test. `steps` is a list of nullary step functions.
+
+### Configuration
+
+```python
+harness.set_timeout(timeout_ms)
+```
+Set the timeout for each test (default: 5000ms).
+
+```python
+harness.set_resetfn(app_reset)
+```
+Set a function to call between tests (to reset/clean up UI state).
+
+### Running Tests
+
+```python
+harness.run_host(app_entry, flags="")
+```
+Harness creates a hidden Tk root and owns the lifecycle. Runs all registered tests, calling `app_entry()` before each test and `app_reset()` (if set) after each test. After all tests complete:
+- If `"x"` in flags: exit mainloop
+- Otherwise: call `app_entry()` one more time to transition into normal runtime
+
+Flags:
+- `"x"` — exit after tests complete
+- `"s"` — show results in a Tk window after tests complete
+
+```python
+harness.attach_harness(root, flags="")
+```
+Attach the harness to an already-running application's root window. Tests run immediately. The `"x"` flag is not allowed (you can't exit an app you don't own).
+
+### Results
+
+```python
+harness.get_results()      # Returns formatted string
+harness.print_results()    # Prints to stdout
+harness.write_results(filepath)  # Writes to file
+harness.show_results()     # Displays in a Tk window
+```
+
+### Accessing State
+
+```python
+harness.tests    # List of test dictionaries (with results after execution)
+harness.g        # Harness state dictionary (includes g["root"])
+```
+
+## Step Function Contract
+
+Each step is a nullary function that returns `(action, value)`:
+
+| Action | Value | Meaning |
+|--------|-------|---------|
+| `"next"` | `None` | Advance to next step immediately |
+| `"next"` | `int` | Advance after N milliseconds |
+| `"wait"` | `int` | Retry this step after N milliseconds |
+| `"goto"` | `int` | Jump to step at index N |
+| `"success"` | `None` | Test passed |
+| `"success"` | `int` | Test passed, finalize after N ms |
+| `"fail"` | `str` | Test failed with message |
+
+If all steps complete without explicit `"success"` or `"fail"`, the test is considered successful.
+
+## Exception Handling
+
+The harness overrides `root.report_callback_exception` to catch exceptions in Tk callbacks. If an exception occurs during a test (in a button handler, `after()` callback, event binding, etc.), the test is immediately marked as failed with the exception traceback captured.
+
+## Test Lifecycle
+
+**With `run_host()`:**
+
+1. Harness creates a hidden Tk root and enters `mainloop()`
+2. For each test:
+   - Call `app_entry()` (create windows, widgets)
+   - Execute steps until success, failure, or timeout
+   - Record result in the test object
+   - Call `app_reset()` if set (clean up for next test)
+3. After all tests:
+   - If `"s"` flag: show results window
+   - If `"x"` flag: exit mainloop
+   - Otherwise: call `app_entry()` to transition into normal app runtime
+
+**With `attach_harness()`:**
+
+1. Attach to existing root window
+2. Run tests immediately
+3. After all tests: app continues running (no exit)
+
+## Two-Track Testing Strategy
+
+For larger applications (20+ files), split tests into two tracks:
+
+- **Track 1: Logic tests** — Pure functions, data processing, validation. Use pytest normally; no Tk needed.
+- **Track 2: GUI tests** — Widget behavior, user interactions. Use tkintertester.
+
+This separation encourages keeping business logic out of GUI code.
+
+## Structuring Your App for Testing
+
+Design your app with `entry()` and `reset()` functions. The CLI or main script sets up the root and calls entry. Tests use the harness.
+
+```python
+# myapp/main.py
+import tkinter as tk
+
+g = {"count": 0}
+widgets = {}
+app = {"root": None, "toplevel": None}
+
+def entry():
+    """Create the UI. app['root'] must be set before calling."""
+    g["count"] = 0
+    app["toplevel"] = tk.Toplevel(app["root"])
+    widgets["label"] = tk.Label(app["toplevel"], text="0")
+    widgets["label"].grid(row=0, column=0)
+    widgets["button"] = tk.Button(
+        app["toplevel"], text="+1",
+        command=handle_when_user_clicks_increment
+    )
+    widgets["button"].grid(row=1, column=0)
+
+def reset():
+    """Tear down the UI between tests."""
+    app["toplevel"].destroy()
+    widgets.clear()
+
+def handle_when_user_clicks_increment():
+    g["count"] += 1
+    widgets["label"].config(text=str(g["count"]))
+```
+
+## Recommended Project Layout
+
+Keep pytest tests and GUI tests in separate directories:
+
+```
+myproject/
+  src/
+    myapp/
+      __init__.py
+      main.py          # has entry(), reset()
+      logic.py         # pure functions, no Tk dependency
+  tests/               # pytest: logic tests (Track 1)
+    test_logic.py
+  guitests/            # tkintertester: GUI tests (Track 2)
+    test_main_window.py
+  pyproject.toml
+```
+
+Configure pytest to only discover tests in `tests/`:
+
+```toml
+# pyproject.toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+```
+
+A GUI test file imports the app and uses the harness:
+
+```python
+# guitests/test_main_window.py
+from tkintertester import harness
+from myapp import main as app
+
+def test_increment():
+    def step_click():
+        app.widgets["button"].invoke()
+        return ("next", None)
+
+    def step_verify():
+        if app.widgets["label"].cget("text") == "1":
+            return ("success", None)
+        return ("fail", "Counter should be 1")
+
+    return [step_click, step_verify]
+
+def app_entry():
+    app.app["root"] = harness.g["root"]
+    app.entry()
+
+harness.add_test("Increment counter", test_increment())
+harness.set_resetfn(app.reset)
+harness.run_host(app_entry, flags="x")
+harness.print_results()
+```
+
+Running tests:
+
+```bash
+python -m pytest                    # runs logic tests (Track 1)
+python guitests/test_main_window.py # runs GUI tests (Track 2)
+```
+
+## Full Documentation
+
+[docs/reference.md](docs/reference.md)
+
+## License
+
+CC0 1.0 Universal — Public Domain