wintestkit 0.1.1rc1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. wintestkit-0.1.1rc1/.gitignore +20 -0
  2. wintestkit-0.1.1rc1/LICENSE +21 -0
  3. wintestkit-0.1.1rc1/PKG-INFO +130 -0
  4. wintestkit-0.1.1rc1/README.md +110 -0
  5. wintestkit-0.1.1rc1/junit-python.xml +1 -0
  6. wintestkit-0.1.1rc1/pyproject.toml +72 -0
  7. wintestkit-0.1.1rc1/src/wintestkit/__init__.py +141 -0
  8. wintestkit-0.1.1rc1/src/wintestkit/__main__.py +5 -0
  9. wintestkit-0.1.1rc1/src/wintestkit/app.py +264 -0
  10. wintestkit-0.1.1rc1/src/wintestkit/artifacts.py +194 -0
  11. wintestkit-0.1.1rc1/src/wintestkit/cli.py +136 -0
  12. wintestkit-0.1.1rc1/src/wintestkit/commands/__init__.py +6 -0
  13. wintestkit-0.1.1rc1/src/wintestkit/commands/check.py +61 -0
  14. wintestkit-0.1.1rc1/src/wintestkit/commands/common.py +80 -0
  15. wintestkit-0.1.1rc1/src/wintestkit/commands/discover.py +78 -0
  16. wintestkit-0.1.1rc1/src/wintestkit/commands/doctor.py +49 -0
  17. wintestkit-0.1.1rc1/src/wintestkit/commands/highlight.py +82 -0
  18. wintestkit-0.1.1rc1/src/wintestkit/commands/import_namemapping.py +34 -0
  19. wintestkit-0.1.1rc1/src/wintestkit/commands/init.py +124 -0
  20. wintestkit-0.1.1rc1/src/wintestkit/commands/inspect.py +126 -0
  21. wintestkit-0.1.1rc1/src/wintestkit/commands/report.py +42 -0
  22. wintestkit-0.1.1rc1/src/wintestkit/commands/run.py +126 -0
  23. wintestkit-0.1.1rc1/src/wintestkit/commands/serve.py +17 -0
  24. wintestkit-0.1.1rc1/src/wintestkit/commands/spy.py +59 -0
  25. wintestkit-0.1.1rc1/src/wintestkit/commands/unused.py +121 -0
  26. wintestkit-0.1.1rc1/src/wintestkit/config.py +462 -0
  27. wintestkit-0.1.1rc1/src/wintestkit/controls.py +231 -0
  28. wintestkit-0.1.1rc1/src/wintestkit/coverage.py +445 -0
  29. wintestkit-0.1.1rc1/src/wintestkit/discovery.py +1229 -0
  30. wintestkit-0.1.1rc1/src/wintestkit/doctor.py +392 -0
  31. wintestkit-0.1.1rc1/src/wintestkit/engine/__init__.py +1 -0
  32. wintestkit-0.1.1rc1/src/wintestkit/engine/actions.py +496 -0
  33. wintestkit-0.1.1rc1/src/wintestkit/engine/diagnose.py +468 -0
  34. wintestkit-0.1.1rc1/src/wintestkit/engine/locator.py +405 -0
  35. wintestkit-0.1.1rc1/src/wintestkit/engine/overlay.py +266 -0
  36. wintestkit-0.1.1rc1/src/wintestkit/engine/properties.py +327 -0
  37. wintestkit-0.1.1rc1/src/wintestkit/engine/query.py +87 -0
  38. wintestkit-0.1.1rc1/src/wintestkit/engine/relocate.py +150 -0
  39. wintestkit-0.1.1rc1/src/wintestkit/engine/resolve.py +218 -0
  40. wintestkit-0.1.1rc1/src/wintestkit/engine/spy.py +228 -0
  41. wintestkit-0.1.1rc1/src/wintestkit/engine/suggest.py +303 -0
  42. wintestkit-0.1.1rc1/src/wintestkit/engine/treedump.py +137 -0
  43. wintestkit-0.1.1rc1/src/wintestkit/engine/waits.py +139 -0
  44. wintestkit-0.1.1rc1/src/wintestkit/errors.py +117 -0
  45. wintestkit-0.1.1rc1/src/wintestkit/events.py +120 -0
  46. wintestkit-0.1.1rc1/src/wintestkit/expect.py +348 -0
  47. wintestkit-0.1.1rc1/src/wintestkit/model.py +1433 -0
  48. wintestkit-0.1.1rc1/src/wintestkit/name_mapping.py +113 -0
  49. wintestkit-0.1.1rc1/src/wintestkit/object_previews.py +345 -0
  50. wintestkit-0.1.1rc1/src/wintestkit/protocol.py +3 -0
  51. wintestkit-0.1.1rc1/src/wintestkit/py.typed +0 -0
  52. wintestkit-0.1.1rc1/src/wintestkit/pytest_plugin.py +713 -0
  53. wintestkit-0.1.1rc1/src/wintestkit/replay.py +160 -0
  54. wintestkit-0.1.1rc1/src/wintestkit/report/__init__.py +1 -0
  55. wintestkit-0.1.1rc1/src/wintestkit/report/html.py +48 -0
  56. wintestkit-0.1.1rc1/src/wintestkit/report/results.py +139 -0
  57. wintestkit-0.1.1rc1/src/wintestkit/report/template.html +677 -0
  58. wintestkit-0.1.1rc1/src/wintestkit/runtime.py +322 -0
  59. wintestkit-0.1.1rc1/src/wintestkit/scaffold/__init__.py +1 -0
  60. wintestkit-0.1.1rc1/src/wintestkit/scaffold/flow_main.py.tmpl +13 -0
  61. wintestkit-0.1.1rc1/src/wintestkit/scaffold/main.py.tmpl +8 -0
  62. wintestkit-0.1.1rc1/src/wintestkit/scaffold/pytest.toml.tmpl +3 -0
  63. wintestkit-0.1.1rc1/src/wintestkit/scaffold/skills/wintestkit-tests/SKILL.md +294 -0
  64. wintestkit-0.1.1rc1/src/wintestkit/scaffold/skills/wintestkit-tests/references/api.md +119 -0
  65. wintestkit-0.1.1rc1/src/wintestkit/scaffold/skills/wintestkit-tests/references/fixing-breakages.md +61 -0
  66. wintestkit-0.1.1rc1/src/wintestkit/scaffold/skills/wintestkit-tests/references/migration-from-testcomplete.md +78 -0
  67. wintestkit-0.1.1rc1/src/wintestkit/scaffold/test_smoke.py.tmpl +8 -0
  68. wintestkit-0.1.1rc1/src/wintestkit/server.py +726 -0
  69. wintestkit-0.1.1rc1/src/wintestkit/targets.py +551 -0
  70. wintestkit-0.1.1rc1/src/wintestkit/uia/__init__.py +5 -0
  71. wintestkit-0.1.1rc1/src/wintestkit/uia/com.py +188 -0
  72. wintestkit-0.1.1rc1/src/wintestkit/uia/constants.py +242 -0
  73. wintestkit-0.1.1rc1/src/wintestkit/uia/dpi.py +42 -0
  74. wintestkit-0.1.1rc1/src/wintestkit/uia/element.py +479 -0
  75. wintestkit-0.1.1rc1/src/wintestkit/uia/input.py +251 -0
  76. wintestkit-0.1.1rc1/src/wintestkit/uia/patterns.py +302 -0
  77. wintestkit-0.1.1rc1/src/wintestkit/uia/png.py +32 -0
  78. wintestkit-0.1.1rc1/src/wintestkit/uia/screenshot.py +276 -0
  79. wintestkit-0.1.1rc1/src/wintestkit/uia/webp.py +16 -0
  80. wintestkit-0.1.1rc1/src/wintestkit/uia/win32.py +629 -0
  81. wintestkit-0.1.1rc1/tests/conftest.py +17 -0
  82. wintestkit-0.1.1rc1/tests/contract/conftest.py +37 -0
  83. wintestkit-0.1.1rc1/tests/contract/fixtures/describe_cases.json +133 -0
  84. wintestkit-0.1.1rc1/tests/contract/fixtures/diagnostic.json +59 -0
  85. wintestkit-0.1.1rc1/tests/contract/fixtures/discovery.json +118 -0
  86. wintestkit-0.1.1rc1/tests/contract/fixtures/element-info.json +21 -0
  87. wintestkit-0.1.1rc1/tests/contract/fixtures/events.ndjson +7 -0
  88. wintestkit-0.1.1rc1/tests/contract/fixtures/inspection-property.json +11 -0
  89. wintestkit-0.1.1rc1/tests/contract/fixtures/results.json +68 -0
  90. wintestkit-0.1.1rc1/tests/contract/fixtures/step.json +14 -0
  91. wintestkit-0.1.1rc1/tests/contract/fixtures/suggestion.json +32 -0
  92. wintestkit-0.1.1rc1/tests/contract/test_discovery_contract.py +93 -0
  93. wintestkit-0.1.1rc1/tests/contract/test_events_contract.py +299 -0
  94. wintestkit-0.1.1rc1/tests/contract/test_results_contract.py +228 -0
  95. wintestkit-0.1.1rc1/tests/contract/test_rpc_contract.py +91 -0
  96. wintestkit-0.1.1rc1/tests/contract/test_schemas.py +430 -0
  97. wintestkit-0.1.1rc1/tests/contract/test_suggest_contract.py +21 -0
  98. wintestkit-0.1.1rc1/tests/contract/test_targets_contract.py +36 -0
  99. wintestkit-0.1.1rc1/tests/integration/test_app.py +24 -0
  100. wintestkit-0.1.1rc1/tests/integration/test_com.py +78 -0
  101. wintestkit-0.1.1rc1/tests/integration/test_overlay.py +30 -0
  102. wintestkit-0.1.1rc1/tests/integration/test_replay.py +69 -0
  103. wintestkit-0.1.1rc1/tests/integration/test_screenshot.py +32 -0
  104. wintestkit-0.1.1rc1/tests/rpc_support.py +54 -0
  105. wintestkit-0.1.1rc1/tests/unit/fakes.py +168 -0
  106. wintestkit-0.1.1rc1/tests/unit/test_cli.py +451 -0
  107. wintestkit-0.1.1rc1/tests/unit/test_com_bootstrap.py +56 -0
  108. wintestkit-0.1.1rc1/tests/unit/test_components.py +520 -0
  109. wintestkit-0.1.1rc1/tests/unit/test_config.py +320 -0
  110. wintestkit-0.1.1rc1/tests/unit/test_constants.py +102 -0
  111. wintestkit-0.1.1rc1/tests/unit/test_coverage.py +379 -0
  112. wintestkit-0.1.1rc1/tests/unit/test_discovery.py +891 -0
  113. wintestkit-0.1.1rc1/tests/unit/test_doctor.py +237 -0
  114. wintestkit-0.1.1rc1/tests/unit/test_element_info.py +72 -0
  115. wintestkit-0.1.1rc1/tests/unit/test_errors.py +100 -0
  116. wintestkit-0.1.1rc1/tests/unit/test_events.py +221 -0
  117. wintestkit-0.1.1rc1/tests/unit/test_expect.py +401 -0
  118. wintestkit-0.1.1rc1/tests/unit/test_flow_discovery.py +107 -0
  119. wintestkit-0.1.1rc1/tests/unit/test_flow_run.py +125 -0
  120. wintestkit-0.1.1rc1/tests/unit/test_foreground.py +201 -0
  121. wintestkit-0.1.1rc1/tests/unit/test_guide_samples.py +108 -0
  122. wintestkit-0.1.1rc1/tests/unit/test_host_window.py +44 -0
  123. wintestkit-0.1.1rc1/tests/unit/test_hosted_windows.py +39 -0
  124. wintestkit-0.1.1rc1/tests/unit/test_init.py +163 -0
  125. wintestkit-0.1.1rc1/tests/unit/test_input_safety.py +137 -0
  126. wintestkit-0.1.1rc1/tests/unit/test_inspect_cmd.py +67 -0
  127. wintestkit-0.1.1rc1/tests/unit/test_keys.py +100 -0
  128. wintestkit-0.1.1rc1/tests/unit/test_launch_app.py +98 -0
  129. wintestkit-0.1.1rc1/tests/unit/test_locator.py +154 -0
  130. wintestkit-0.1.1rc1/tests/unit/test_model.py +701 -0
  131. wintestkit-0.1.1rc1/tests/unit/test_name_mapping.py +114 -0
  132. wintestkit-0.1.1rc1/tests/unit/test_object_previews.py +524 -0
  133. wintestkit-0.1.1rc1/tests/unit/test_object_previews_config.py +73 -0
  134. wintestkit-0.1.1rc1/tests/unit/test_overlay.py +47 -0
  135. wintestkit-0.1.1rc1/tests/unit/test_plugin.py +409 -0
  136. wintestkit-0.1.1rc1/tests/unit/test_png.py +63 -0
  137. wintestkit-0.1.1rc1/tests/unit/test_properties.py +362 -0
  138. wintestkit-0.1.1rc1/tests/unit/test_public_api.py +116 -0
  139. wintestkit-0.1.1rc1/tests/unit/test_release.py +323 -0
  140. wintestkit-0.1.1rc1/tests/unit/test_relocation.py +409 -0
  141. wintestkit-0.1.1rc1/tests/unit/test_replay.py +216 -0
  142. wintestkit-0.1.1rc1/tests/unit/test_replay_window.py +123 -0
  143. wintestkit-0.1.1rc1/tests/unit/test_report.py +200 -0
  144. wintestkit-0.1.1rc1/tests/unit/test_resolve.py +329 -0
  145. wintestkit-0.1.1rc1/tests/unit/test_runtime.py +260 -0
  146. wintestkit-0.1.1rc1/tests/unit/test_screenshot.py +101 -0
  147. wintestkit-0.1.1rc1/tests/unit/test_server.py +600 -0
  148. wintestkit-0.1.1rc1/tests/unit/test_server_lifecycle_inspection.py +434 -0
  149. wintestkit-0.1.1rc1/tests/unit/test_smoke.py +39 -0
  150. wintestkit-0.1.1rc1/tests/unit/test_spy.py +93 -0
  151. wintestkit-0.1.1rc1/tests/unit/test_suggest.py +195 -0
  152. wintestkit-0.1.1rc1/tests/unit/test_target_commands.py +221 -0
  153. wintestkit-0.1.1rc1/tests/unit/test_targets.py +230 -0
  154. wintestkit-0.1.1rc1/tests/unit/test_traceback_hiding.py +62 -0
  155. wintestkit-0.1.1rc1/tests/unit/test_tree_diff.py +149 -0
  156. wintestkit-0.1.1rc1/tests/unit/test_typed_elements.py +599 -0
  157. wintestkit-0.1.1rc1/tests/unit/test_typing.py +141 -0
  158. wintestkit-0.1.1rc1/tests/unit/test_unused_command.py +75 -0
  159. wintestkit-0.1.1rc1/tests/unit/test_waits.py +258 -0
  160. wintestkit-0.1.1rc1/tests/unit/test_yaml_config.py +71 -0
  161. wintestkit-0.1.1rc1/uv.lock +962 -0
@@ -0,0 +1,20 @@
1
+ __pycache__/
2
+ wintestkit.local.toml
3
+ wintestkit.local.yaml
4
+ .venv/
5
+ *.egg-info/
6
+ dist/
7
+ .pytest_cache/
8
+ .pytest-*/
9
+ .ruff_cache/
10
+ node_modules/
11
+ vscode/dist/
12
+ vscode/out/
13
+ *.vsix
14
+ demo/**/bin/
15
+ demo/**/obj/
16
+ wtk-report/
17
+ wtk-results/
18
+ .vscode-test/
19
+ vscode/media/codicons/
20
+ vscode/media/report/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Massimo Nodin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.5
2
+ Name: wintestkit
3
+ Version: 0.1.1rc1
4
+ Summary: UI test automation for Windows WPF applications
5
+ Project-URL: Homepage, https://github.com/MassimoNodin/wintestkit
6
+ Project-URL: Documentation, https://github.com/MassimoNodin/wintestkit/tree/master/docs/guide
7
+ Project-URL: Repository, https://github.com/MassimoNodin/wintestkit
8
+ Project-URL: Issues, https://github.com/MassimoNodin/wintestkit/issues
9
+ Project-URL: Changelog, https://github.com/MassimoNodin/wintestkit/blob/master/vscode/CHANGELOG.md
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Classifier: Framework :: Pytest
13
+ Classifier: Operating System :: Microsoft :: Windows
14
+ Requires-Python: >=3.12
15
+ Requires-Dist: comtypes>=1.4.8
16
+ Requires-Dist: pillow>=12.0.0
17
+ Requires-Dist: pytest>=8.3
18
+ Requires-Dist: pyyaml>=6.0.2
19
+ Description-Content-Type: text/markdown
20
+
21
+ # WinTestKit
22
+
23
+ UI test automation for Windows WPF applications using Microsoft UI Automation and pytest.
24
+
25
+ The package includes a UI Automation engine, page/element model, pytest integration,
26
+ static discovery, environment checks, and target-based highlighting and page checks.
27
+
28
+ ## Installation
29
+
30
+ Requires Windows and Python 3.12 or later:
31
+
32
+ ```powershell
33
+ python -m pip install wintestkit
34
+ wtk --version
35
+ ```
36
+
37
+ pytest is installed automatically. For the editor tools, install the WinTestKit VS Code
38
+ extension and select the Python environment containing this package. See the
39
+ [user guide](https://github.com/MassimoNodin/wintestkit/blob/master/docs/guide/index.md).
40
+
41
+ ## Initialize a project
42
+
43
+ Run `wtk init my-tests --app "C:/Apps/My App.exe"` to create a starter page,
44
+ smoke test, pytest configuration, and report ignore entry. Existing metadata,
45
+ configuration, and Python files are preserved. `--force` replaces starter Python
46
+ files only; it does not overwrite application settings. The generated `MainPage` in
47
+ `pages/main.py` is a VS Code walkthrough example: it targets the frontmost `Code.exe`
48
+ window and its second direct UI Automation child, without relying on the workspace title.
49
+ The smoke test and starter flow check both. For your own application, replace these example
50
+ locators with its window and controls before running `wtk doctor` and `wtk run`.
51
+
52
+ ## Development
53
+
54
+ From this directory, with Python 3.12+ and uv installed:
55
+
56
+ ```powershell
57
+ uv sync
58
+ uv run pytest -m "not integration"
59
+ uv run wtk --help
60
+ uv run python -m wintestkit --version
61
+ uv run ruff check .
62
+ uv run ruff format --check .
63
+ uv run pyright
64
+ ```
65
+
66
+ No example app is bundled. Native desktop tests require an interactive, unlocked Windows
67
+ session, but no external demo executable. See the
68
+ [development guide](https://github.com/MassimoNodin/wintestkit/blob/master/docs/development.md)
69
+ for desktop tests and packaging, and the
70
+ [Calculator example](https://github.com/MassimoNodin/wintestkit/tree/master/examples/calculator-tests)
71
+ for application-level scenarios.
72
+
73
+ ## Resolve targets
74
+
75
+ Open Windows Calculator in Standard mode before running these commands from this directory.
76
+ For your own application, replace the project root and page targets:
77
+
78
+ ```powershell
79
+ uv run wtk --root ../examples/calculator-tests highlight pages/calculator.py::CalculatorPage.one --json
80
+ uv run wtk --root ../examples/calculator-tests highlight pages/standard.py::StandardPage --duration 1000
81
+ uv run wtk --root ../examples/calculator-tests check pages/standard.py::StandardPage --json
82
+ ```
83
+
84
+ `highlight` resolves immediately by default; `--timeout S` enables polling. It brings the
85
+ owning window to the foreground before drawing the outline. If Windows denies that, the
86
+ outline is still drawn. `--launch` starts
87
+ the configured app only if it is not running, and closes only an app launched by that command.
88
+ `check` resolves every declared element without waiting. Hidden menu items, collapsed content
89
+ and unrealized collection items can legitimately fail until the UI exposes them. Exit codes
90
+ are 0 for found/all found, 1 for resolution failures, 2 for invalid targets/configuration,
91
+ and 3 for an app that is not running. User modules reload when project Python files change.
92
+
93
+ ## Inspect the application
94
+
95
+ `wtk inspect` dumps the configured app main window. Use `--window TITLE` or
96
+ `--window /REGEX/` to select a window, `--all-windows` to inspect all app windows,
97
+ and `--depth N` to bound tree expansion (0 to 50, default 12). `--json` emits a
98
+ tree object, or a `windows` array for `--all-windows`.
99
+
100
+ `wtk inspect --at X,Y --json` reports the app element and its nearest-first
101
+ ancestor chain, including supported patterns. Coordinates are physical page
102
+ pixels; use `--at=-100,200` for negative coordinates. Button text is normalized
103
+ to its containing button. Points outside the configured app fail without
104
+ inspecting another process. Window and point selection options are mutually exclusive.
105
+
106
+ The suggestion engine (`wintestkit.engine.suggest`) verifies generated locators
107
+ against the selected element, prioritizing stable IDs, names, classes, scoped
108
+ ancestors, and finally positional indices. Helpers precede dependent declarations;
109
+ index suggestions are fragile if the UI order changes. When an element is globally
110
+ unique, candidate ordering selects simpler properties such as `class_name` rather
111
+ than nested container scopes.
112
+
113
+ ## Pick locators
114
+
115
+ `wtk spy` highlights hovered controls in the configured application. Ctrl+Click
116
+ picks a control without activating it and prints its window, required helpers,
117
+ and element declaration. Esc or Ctrl+C exits and removes the hooks and overlay.
118
+ Use `--all-processes` explicitly to inspect other applications. The command does
119
+ not launch an application or change elevation; it requires an unlocked desktop.
120
+
121
+ ## Editor server
122
+
123
+ `wtk serve --stdio` accepts one JSON-RPC 2.0 object per UTF-8 line. Send
124
+ `initialize` with `{ "root": "absolute/project/path" }` first. It supports
125
+ discovery, app lifecycle, target checks/highlights, inspector nodes, suggestions,
126
+ and Spy notifications, as specified in `schemas/rpc.schema.json`. Ordinary
127
+ requests execute sequentially; Spy stop and shutdown bypass queued work.
128
+ Standard output is protocol-only, including when user modules print. Shutdown
129
+ and input EOF clean up Spy but leave the application open. Inspector node IDs
130
+ are runtime IDs held in a bounded 5,000-entry LRU; stale IDs return `-32005`.
@@ -0,0 +1,110 @@
1
+ # WinTestKit
2
+
3
+ UI test automation for Windows WPF applications using Microsoft UI Automation and pytest.
4
+
5
+ The package includes a UI Automation engine, page/element model, pytest integration,
6
+ static discovery, environment checks, and target-based highlighting and page checks.
7
+
8
+ ## Installation
9
+
10
+ Requires Windows and Python 3.12 or later:
11
+
12
+ ```powershell
13
+ python -m pip install wintestkit
14
+ wtk --version
15
+ ```
16
+
17
+ pytest is installed automatically. For the editor tools, install the WinTestKit VS Code
18
+ extension and select the Python environment containing this package. See the
19
+ [user guide](https://github.com/MassimoNodin/wintestkit/blob/master/docs/guide/index.md).
20
+
21
+ ## Initialize a project
22
+
23
+ Run `wtk init my-tests --app "C:/Apps/My App.exe"` to create a starter page,
24
+ smoke test, pytest configuration, and report ignore entry. Existing metadata,
25
+ configuration, and Python files are preserved. `--force` replaces starter Python
26
+ files only; it does not overwrite application settings. The generated `MainPage` in
27
+ `pages/main.py` is a VS Code walkthrough example: it targets the frontmost `Code.exe`
28
+ window and its second direct UI Automation child, without relying on the workspace title.
29
+ The smoke test and starter flow check both. For your own application, replace these example
30
+ locators with its window and controls before running `wtk doctor` and `wtk run`.
31
+
32
+ ## Development
33
+
34
+ From this directory, with Python 3.12+ and uv installed:
35
+
36
+ ```powershell
37
+ uv sync
38
+ uv run pytest -m "not integration"
39
+ uv run wtk --help
40
+ uv run python -m wintestkit --version
41
+ uv run ruff check .
42
+ uv run ruff format --check .
43
+ uv run pyright
44
+ ```
45
+
46
+ No example app is bundled. Native desktop tests require an interactive, unlocked Windows
47
+ session, but no external demo executable. See the
48
+ [development guide](https://github.com/MassimoNodin/wintestkit/blob/master/docs/development.md)
49
+ for desktop tests and packaging, and the
50
+ [Calculator example](https://github.com/MassimoNodin/wintestkit/tree/master/examples/calculator-tests)
51
+ for application-level scenarios.
52
+
53
+ ## Resolve targets
54
+
55
+ Open Windows Calculator in Standard mode before running these commands from this directory.
56
+ For your own application, replace the project root and page targets:
57
+
58
+ ```powershell
59
+ uv run wtk --root ../examples/calculator-tests highlight pages/calculator.py::CalculatorPage.one --json
60
+ uv run wtk --root ../examples/calculator-tests highlight pages/standard.py::StandardPage --duration 1000
61
+ uv run wtk --root ../examples/calculator-tests check pages/standard.py::StandardPage --json
62
+ ```
63
+
64
+ `highlight` resolves immediately by default; `--timeout S` enables polling. It brings the
65
+ owning window to the foreground before drawing the outline. If Windows denies that, the
66
+ outline is still drawn. `--launch` starts
67
+ the configured app only if it is not running, and closes only an app launched by that command.
68
+ `check` resolves every declared element without waiting. Hidden menu items, collapsed content
69
+ and unrealized collection items can legitimately fail until the UI exposes them. Exit codes
70
+ are 0 for found/all found, 1 for resolution failures, 2 for invalid targets/configuration,
71
+ and 3 for an app that is not running. User modules reload when project Python files change.
72
+
73
+ ## Inspect the application
74
+
75
+ `wtk inspect` dumps the configured app main window. Use `--window TITLE` or
76
+ `--window /REGEX/` to select a window, `--all-windows` to inspect all app windows,
77
+ and `--depth N` to bound tree expansion (0 to 50, default 12). `--json` emits a
78
+ tree object, or a `windows` array for `--all-windows`.
79
+
80
+ `wtk inspect --at X,Y --json` reports the app element and its nearest-first
81
+ ancestor chain, including supported patterns. Coordinates are physical page
82
+ pixels; use `--at=-100,200` for negative coordinates. Button text is normalized
83
+ to its containing button. Points outside the configured app fail without
84
+ inspecting another process. Window and point selection options are mutually exclusive.
85
+
86
+ The suggestion engine (`wintestkit.engine.suggest`) verifies generated locators
87
+ against the selected element, prioritizing stable IDs, names, classes, scoped
88
+ ancestors, and finally positional indices. Helpers precede dependent declarations;
89
+ index suggestions are fragile if the UI order changes. When an element is globally
90
+ unique, candidate ordering selects simpler properties such as `class_name` rather
91
+ than nested container scopes.
92
+
93
+ ## Pick locators
94
+
95
+ `wtk spy` highlights hovered controls in the configured application. Ctrl+Click
96
+ picks a control without activating it and prints its window, required helpers,
97
+ and element declaration. Esc or Ctrl+C exits and removes the hooks and overlay.
98
+ Use `--all-processes` explicitly to inspect other applications. The command does
99
+ not launch an application or change elevation; it requires an unlocked desktop.
100
+
101
+ ## Editor server
102
+
103
+ `wtk serve --stdio` accepts one JSON-RPC 2.0 object per UTF-8 line. Send
104
+ `initialize` with `{ "root": "absolute/project/path" }` first. It supports
105
+ discovery, app lifecycle, target checks/highlights, inspector nodes, suggestions,
106
+ and Spy notifications, as specified in `schemas/rpc.schema.json`. Ordinary
107
+ requests execute sequentially; Spy stop and shutdown bypass queued work.
108
+ Standard output is protocol-only, including when user modules print. Shutdown
109
+ and input EOF clean up Spy but leave the application open. Inspector node IDs
110
+ are runtime IDs held in a bounded 5,000-entry LRU; stale IDs return `-32005`.