mindheal 1.0.0

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 (255) hide show
  1. package/.env.example +48 -0
  2. package/CHANGELOG.md +27 -0
  3. package/LICENSE +21 -0
  4. package/README.md +481 -0
  5. package/dist/cjs/ai/ai-provider.js +46 -0
  6. package/dist/cjs/ai/ai-provider.js.map +1 -0
  7. package/dist/cjs/ai/anthropic-provider.js +106 -0
  8. package/dist/cjs/ai/anthropic-provider.js.map +1 -0
  9. package/dist/cjs/ai/azure-openai-provider.js +130 -0
  10. package/dist/cjs/ai/azure-openai-provider.js.map +1 -0
  11. package/dist/cjs/ai/bedrock-provider.js +183 -0
  12. package/dist/cjs/ai/bedrock-provider.js.map +1 -0
  13. package/dist/cjs/ai/deepseek-provider.js +118 -0
  14. package/dist/cjs/ai/deepseek-provider.js.map +1 -0
  15. package/dist/cjs/ai/gemini-provider.js +129 -0
  16. package/dist/cjs/ai/gemini-provider.js.map +1 -0
  17. package/dist/cjs/ai/groq-provider.js +118 -0
  18. package/dist/cjs/ai/groq-provider.js.map +1 -0
  19. package/dist/cjs/ai/meta-provider.js +118 -0
  20. package/dist/cjs/ai/meta-provider.js.map +1 -0
  21. package/dist/cjs/ai/ollama-provider.js +127 -0
  22. package/dist/cjs/ai/ollama-provider.js.map +1 -0
  23. package/dist/cjs/ai/openai-provider.js +117 -0
  24. package/dist/cjs/ai/openai-provider.js.map +1 -0
  25. package/dist/cjs/ai/perplexity-provider.js +118 -0
  26. package/dist/cjs/ai/perplexity-provider.js.map +1 -0
  27. package/dist/cjs/ai/prompt-templates.js +174 -0
  28. package/dist/cjs/ai/prompt-templates.js.map +1 -0
  29. package/dist/cjs/ai/qwen-provider.js +118 -0
  30. package/dist/cjs/ai/qwen-provider.js.map +1 -0
  31. package/dist/cjs/analytics/healing-analytics.js +263 -0
  32. package/dist/cjs/analytics/healing-analytics.js.map +1 -0
  33. package/dist/cjs/cli/init.js +517 -0
  34. package/dist/cjs/cli/init.js.map +1 -0
  35. package/dist/cjs/config/config-loader.js +135 -0
  36. package/dist/cjs/config/config-loader.js.map +1 -0
  37. package/dist/cjs/config/defaults.js +109 -0
  38. package/dist/cjs/config/defaults.js.map +1 -0
  39. package/dist/cjs/core/dom-snapshot.js +280 -0
  40. package/dist/cjs/core/dom-snapshot.js.map +1 -0
  41. package/dist/cjs/core/enterprise-strategy.js +702 -0
  42. package/dist/cjs/core/enterprise-strategy.js.map +1 -0
  43. package/dist/cjs/core/healer.js +283 -0
  44. package/dist/cjs/core/healer.js.map +1 -0
  45. package/dist/cjs/core/interceptor.js +945 -0
  46. package/dist/cjs/core/interceptor.js.map +1 -0
  47. package/dist/cjs/core/locator-analyzer.js +172 -0
  48. package/dist/cjs/core/locator-analyzer.js.map +1 -0
  49. package/dist/cjs/core/locator-strategies.js +891 -0
  50. package/dist/cjs/core/locator-strategies.js.map +1 -0
  51. package/dist/cjs/core/self-heal-cache.js +178 -0
  52. package/dist/cjs/core/self-heal-cache.js.map +1 -0
  53. package/dist/cjs/core/smart-retry.js +248 -0
  54. package/dist/cjs/core/smart-retry.js.map +1 -0
  55. package/dist/cjs/core/visual-verification.js +262 -0
  56. package/dist/cjs/core/visual-verification.js.map +1 -0
  57. package/dist/cjs/git/code-modifier.js +184 -0
  58. package/dist/cjs/git/code-modifier.js.map +1 -0
  59. package/dist/cjs/git/git-operations.js +145 -0
  60. package/dist/cjs/git/git-operations.js.map +1 -0
  61. package/dist/cjs/git/pr-creator.js +190 -0
  62. package/dist/cjs/git/pr-creator.js.map +1 -0
  63. package/dist/cjs/index.js +97 -0
  64. package/dist/cjs/index.js.map +1 -0
  65. package/dist/cjs/rag/context-retriever.js +289 -0
  66. package/dist/cjs/rag/context-retriever.js.map +1 -0
  67. package/dist/cjs/rag/embeddings.js +82 -0
  68. package/dist/cjs/rag/embeddings.js.map +1 -0
  69. package/dist/cjs/rag/knowledge-store.js +159 -0
  70. package/dist/cjs/rag/knowledge-store.js.map +1 -0
  71. package/dist/cjs/reporters/heal-report.js +279 -0
  72. package/dist/cjs/reporters/heal-report.js.map +1 -0
  73. package/dist/cjs/reporters/heal-reporter.js +294 -0
  74. package/dist/cjs/reporters/heal-reporter.js.map +1 -0
  75. package/dist/cjs/server/review-server.js +166 -0
  76. package/dist/cjs/server/review-server.js.map +1 -0
  77. package/dist/cjs/server/routes.js +92 -0
  78. package/dist/cjs/server/routes.js.map +1 -0
  79. package/dist/cjs/utils/environment.js +57 -0
  80. package/dist/cjs/utils/environment.js.map +1 -0
  81. package/dist/cjs/utils/file-lock.js +136 -0
  82. package/dist/cjs/utils/file-lock.js.map +1 -0
  83. package/dist/cjs/utils/file-utils.js +49 -0
  84. package/dist/cjs/utils/file-utils.js.map +1 -0
  85. package/dist/cjs/utils/logger.js +78 -0
  86. package/dist/cjs/utils/logger.js.map +1 -0
  87. package/dist/esm/ai/ai-provider.js +44 -0
  88. package/dist/esm/ai/ai-provider.js.map +1 -0
  89. package/dist/esm/ai/anthropic-provider.js +104 -0
  90. package/dist/esm/ai/anthropic-provider.js.map +1 -0
  91. package/dist/esm/ai/azure-openai-provider.js +128 -0
  92. package/dist/esm/ai/azure-openai-provider.js.map +1 -0
  93. package/dist/esm/ai/bedrock-provider.js +181 -0
  94. package/dist/esm/ai/bedrock-provider.js.map +1 -0
  95. package/dist/esm/ai/deepseek-provider.js +116 -0
  96. package/dist/esm/ai/deepseek-provider.js.map +1 -0
  97. package/dist/esm/ai/gemini-provider.js +127 -0
  98. package/dist/esm/ai/gemini-provider.js.map +1 -0
  99. package/dist/esm/ai/groq-provider.js +116 -0
  100. package/dist/esm/ai/groq-provider.js.map +1 -0
  101. package/dist/esm/ai/meta-provider.js +116 -0
  102. package/dist/esm/ai/meta-provider.js.map +1 -0
  103. package/dist/esm/ai/ollama-provider.js +125 -0
  104. package/dist/esm/ai/ollama-provider.js.map +1 -0
  105. package/dist/esm/ai/openai-provider.js +115 -0
  106. package/dist/esm/ai/openai-provider.js.map +1 -0
  107. package/dist/esm/ai/perplexity-provider.js +116 -0
  108. package/dist/esm/ai/perplexity-provider.js.map +1 -0
  109. package/dist/esm/ai/prompt-templates.js +171 -0
  110. package/dist/esm/ai/prompt-templates.js.map +1 -0
  111. package/dist/esm/ai/qwen-provider.js +116 -0
  112. package/dist/esm/ai/qwen-provider.js.map +1 -0
  113. package/dist/esm/analytics/healing-analytics.js +261 -0
  114. package/dist/esm/analytics/healing-analytics.js.map +1 -0
  115. package/dist/esm/cli/init.js +495 -0
  116. package/dist/esm/cli/init.js.map +1 -0
  117. package/dist/esm/config/config-loader.js +132 -0
  118. package/dist/esm/config/config-loader.js.map +1 -0
  119. package/dist/esm/config/defaults.js +107 -0
  120. package/dist/esm/config/defaults.js.map +1 -0
  121. package/dist/esm/core/dom-snapshot.js +278 -0
  122. package/dist/esm/core/dom-snapshot.js.map +1 -0
  123. package/dist/esm/core/enterprise-strategy.js +695 -0
  124. package/dist/esm/core/enterprise-strategy.js.map +1 -0
  125. package/dist/esm/core/healer.js +281 -0
  126. package/dist/esm/core/healer.js.map +1 -0
  127. package/dist/esm/core/interceptor.js +940 -0
  128. package/dist/esm/core/interceptor.js.map +1 -0
  129. package/dist/esm/core/locator-analyzer.js +169 -0
  130. package/dist/esm/core/locator-analyzer.js.map +1 -0
  131. package/dist/esm/core/locator-strategies.js +882 -0
  132. package/dist/esm/core/locator-strategies.js.map +1 -0
  133. package/dist/esm/core/self-heal-cache.js +176 -0
  134. package/dist/esm/core/self-heal-cache.js.map +1 -0
  135. package/dist/esm/core/smart-retry.js +246 -0
  136. package/dist/esm/core/smart-retry.js.map +1 -0
  137. package/dist/esm/core/visual-verification.js +260 -0
  138. package/dist/esm/core/visual-verification.js.map +1 -0
  139. package/dist/esm/git/code-modifier.js +182 -0
  140. package/dist/esm/git/code-modifier.js.map +1 -0
  141. package/dist/esm/git/git-operations.js +143 -0
  142. package/dist/esm/git/git-operations.js.map +1 -0
  143. package/dist/esm/git/pr-creator.js +188 -0
  144. package/dist/esm/git/pr-creator.js.map +1 -0
  145. package/dist/esm/index.js +37 -0
  146. package/dist/esm/index.js.map +1 -0
  147. package/dist/esm/rag/context-retriever.js +287 -0
  148. package/dist/esm/rag/context-retriever.js.map +1 -0
  149. package/dist/esm/rag/embeddings.js +77 -0
  150. package/dist/esm/rag/embeddings.js.map +1 -0
  151. package/dist/esm/rag/knowledge-store.js +157 -0
  152. package/dist/esm/rag/knowledge-store.js.map +1 -0
  153. package/dist/esm/reporters/heal-report.js +277 -0
  154. package/dist/esm/reporters/heal-report.js.map +1 -0
  155. package/dist/esm/reporters/heal-reporter.js +290 -0
  156. package/dist/esm/reporters/heal-reporter.js.map +1 -0
  157. package/dist/esm/server/review-server.js +164 -0
  158. package/dist/esm/server/review-server.js.map +1 -0
  159. package/dist/esm/server/routes.js +90 -0
  160. package/dist/esm/server/routes.js.map +1 -0
  161. package/dist/esm/utils/environment.js +53 -0
  162. package/dist/esm/utils/environment.js.map +1 -0
  163. package/dist/esm/utils/file-lock.js +134 -0
  164. package/dist/esm/utils/file-lock.js.map +1 -0
  165. package/dist/esm/utils/file-utils.js +43 -0
  166. package/dist/esm/utils/file-utils.js.map +1 -0
  167. package/dist/esm/utils/logger.js +75 -0
  168. package/dist/esm/utils/logger.js.map +1 -0
  169. package/dist/types/ai/ai-provider.d.ts +4 -0
  170. package/dist/types/ai/ai-provider.d.ts.map +1 -0
  171. package/dist/types/ai/anthropic-provider.d.ts +11 -0
  172. package/dist/types/ai/anthropic-provider.d.ts.map +1 -0
  173. package/dist/types/ai/azure-openai-provider.d.ts +13 -0
  174. package/dist/types/ai/azure-openai-provider.d.ts.map +1 -0
  175. package/dist/types/ai/bedrock-provider.d.ts +14 -0
  176. package/dist/types/ai/bedrock-provider.d.ts.map +1 -0
  177. package/dist/types/ai/deepseek-provider.d.ts +12 -0
  178. package/dist/types/ai/deepseek-provider.d.ts.map +1 -0
  179. package/dist/types/ai/gemini-provider.d.ts +12 -0
  180. package/dist/types/ai/gemini-provider.d.ts.map +1 -0
  181. package/dist/types/ai/groq-provider.d.ts +12 -0
  182. package/dist/types/ai/groq-provider.d.ts.map +1 -0
  183. package/dist/types/ai/meta-provider.d.ts +12 -0
  184. package/dist/types/ai/meta-provider.d.ts.map +1 -0
  185. package/dist/types/ai/ollama-provider.d.ts +10 -0
  186. package/dist/types/ai/ollama-provider.d.ts.map +1 -0
  187. package/dist/types/ai/openai-provider.d.ts +11 -0
  188. package/dist/types/ai/openai-provider.d.ts.map +1 -0
  189. package/dist/types/ai/perplexity-provider.d.ts +12 -0
  190. package/dist/types/ai/perplexity-provider.d.ts.map +1 -0
  191. package/dist/types/ai/prompt-templates.d.ts +11 -0
  192. package/dist/types/ai/prompt-templates.d.ts.map +1 -0
  193. package/dist/types/ai/qwen-provider.d.ts +12 -0
  194. package/dist/types/ai/qwen-provider.d.ts.map +1 -0
  195. package/dist/types/analytics/healing-analytics.d.ts +36 -0
  196. package/dist/types/analytics/healing-analytics.d.ts.map +1 -0
  197. package/dist/types/cli/init.d.ts +15 -0
  198. package/dist/types/cli/init.d.ts.map +1 -0
  199. package/dist/types/config/config-loader.d.ts +4 -0
  200. package/dist/types/config/config-loader.d.ts.map +1 -0
  201. package/dist/types/config/defaults.d.ts +3 -0
  202. package/dist/types/config/defaults.d.ts.map +1 -0
  203. package/dist/types/core/dom-snapshot.d.ts +12 -0
  204. package/dist/types/core/dom-snapshot.d.ts.map +1 -0
  205. package/dist/types/core/enterprise-strategy.d.ts +56 -0
  206. package/dist/types/core/enterprise-strategy.d.ts.map +1 -0
  207. package/dist/types/core/healer.d.ts +52 -0
  208. package/dist/types/core/healer.d.ts.map +1 -0
  209. package/dist/types/core/interceptor.d.ts +64 -0
  210. package/dist/types/core/interceptor.d.ts.map +1 -0
  211. package/dist/types/core/locator-analyzer.d.ts +31 -0
  212. package/dist/types/core/locator-analyzer.d.ts.map +1 -0
  213. package/dist/types/core/locator-strategies.d.ts +45 -0
  214. package/dist/types/core/locator-strategies.d.ts.map +1 -0
  215. package/dist/types/core/self-heal-cache.d.ts +51 -0
  216. package/dist/types/core/self-heal-cache.d.ts.map +1 -0
  217. package/dist/types/core/smart-retry.d.ts +64 -0
  218. package/dist/types/core/smart-retry.d.ts.map +1 -0
  219. package/dist/types/core/visual-verification.d.ts +46 -0
  220. package/dist/types/core/visual-verification.d.ts.map +1 -0
  221. package/dist/types/git/code-modifier.d.ts +51 -0
  222. package/dist/types/git/code-modifier.d.ts.map +1 -0
  223. package/dist/types/git/git-operations.d.ts +40 -0
  224. package/dist/types/git/git-operations.d.ts.map +1 -0
  225. package/dist/types/git/pr-creator.d.ts +27 -0
  226. package/dist/types/git/pr-creator.d.ts.map +1 -0
  227. package/dist/types/index.d.ts +40 -0
  228. package/dist/types/index.d.ts.map +1 -0
  229. package/dist/types/rag/context-retriever.d.ts +69 -0
  230. package/dist/types/rag/context-retriever.d.ts.map +1 -0
  231. package/dist/types/rag/embeddings.d.ts +32 -0
  232. package/dist/types/rag/embeddings.d.ts.map +1 -0
  233. package/dist/types/rag/index.d.ts +12 -0
  234. package/dist/types/rag/index.d.ts.map +1 -0
  235. package/dist/types/rag/knowledge-store.d.ts +38 -0
  236. package/dist/types/rag/knowledge-store.d.ts.map +1 -0
  237. package/dist/types/reporters/heal-report.d.ts +29 -0
  238. package/dist/types/reporters/heal-report.d.ts.map +1 -0
  239. package/dist/types/reporters/heal-reporter.d.ts +49 -0
  240. package/dist/types/reporters/heal-reporter.d.ts.map +1 -0
  241. package/dist/types/server/review-server.d.ts +20 -0
  242. package/dist/types/server/review-server.d.ts.map +1 -0
  243. package/dist/types/server/routes.d.ts +4 -0
  244. package/dist/types/server/routes.d.ts.map +1 -0
  245. package/dist/types/types/index.d.ts +433 -0
  246. package/dist/types/types/index.d.ts.map +1 -0
  247. package/dist/types/utils/environment.d.ts +10 -0
  248. package/dist/types/utils/environment.d.ts.map +1 -0
  249. package/dist/types/utils/file-lock.d.ts +37 -0
  250. package/dist/types/utils/file-lock.d.ts.map +1 -0
  251. package/dist/types/utils/file-utils.d.ts +7 -0
  252. package/dist/types/utils/file-utils.d.ts.map +1 -0
  253. package/dist/types/utils/logger.d.ts +9 -0
  254. package/dist/types/utils/logger.d.ts.map +1 -0
  255. package/package.json +106 -0
package/.env.example ADDED
@@ -0,0 +1,48 @@
1
+ # ─── MindHeal AI Provider Configuration ──────────────────────────────────────
2
+ # Copy this file to .env and fill in the values for your chosen provider.
3
+ # Only ONE provider's API key is needed — whichever you set in mindheal.config.ts
4
+
5
+ # ─── Universal key (used when config has apiKey: process.env.MINDHEAL_API_KEY)
6
+ MINDHEAL_API_KEY=
7
+
8
+ # ─── Anthropic (Claude) ─────────────────────────────────────────────────────
9
+ ANTHROPIC_API_KEY=sk-ant-...
10
+
11
+ # ─── OpenAI ─────────────────────────────────────────────────────────────────
12
+ OPENAI_API_KEY=sk-...
13
+
14
+ # ─── Azure OpenAI ───────────────────────────────────────────────────────────
15
+ AZURE_OPENAI_API_KEY=
16
+ AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
17
+ AZURE_OPENAI_DEPLOYMENT=gpt-4o
18
+ AZURE_OPENAI_API_VERSION=2024-02-01
19
+
20
+ # ─── Google Gemini ──────────────────────────────────────────────────────────
21
+ GEMINI_API_KEY=
22
+
23
+ # ─── Ollama (Local — no API key needed) ─────────────────────────────────────
24
+ OLLAMA_HOST=http://localhost:11434
25
+
26
+ # ─── AWS Bedrock ────────────────────────────────────────────────────────────
27
+ AWS_ACCESS_KEY_ID=
28
+ AWS_SECRET_ACCESS_KEY=
29
+ AWS_SESSION_TOKEN=
30
+ AWS_REGION=us-east-1
31
+
32
+ # ─── DeepSeek ───────────────────────────────────────────────────────────────
33
+ DEEPSEEK_API_KEY=
34
+
35
+ # ─── Groq ───────────────────────────────────────────────────────────────────
36
+ GROQ_API_KEY=gsk_...
37
+
38
+ # ─── Qwen (Alibaba DashScope) ──────────────────────────────────────────────
39
+ QWEN_API_KEY=
40
+
41
+ # ─── Meta (via Together.ai) ────────────────────────────────────────────────
42
+ TOGETHER_API_KEY=
43
+
44
+ # ─── Perplexity ─────────────────────────────────────────────────────────────
45
+ PERPLEXITY_API_KEY=pplx-...
46
+
47
+ # ─── Git (for auto-PR creation) ────────────────────────────────────────────
48
+ GIT_TOKEN=ghp_...
package/CHANGELOG.md ADDED
@@ -0,0 +1,27 @@
1
+ # Changelog
2
+
3
+ All notable changes to MindHeal will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [1.0.0] - 2026-04-08
9
+
10
+ ### Added
11
+
12
+ - **Core Healing Engine** — Proxy-based interception of all 8 Playwright locator methods (`click`, `fill`, `type`, `check`, `uncheck`, `selectOption`, `hover`, `isVisible`)
13
+ - **10 Healing Strategies** — cache, attribute, text, role, css, xpath, table, modal, enterprise, AI+RAG
14
+ - **11 AI Providers** — Anthropic (Claude), OpenAI, Azure OpenAI, Google Gemini, Ollama (local), AWS Bedrock, DeepSeek, Groq, Qwen, Meta/Llama, Perplexity
15
+ - **Enterprise Application Support** — Dynamic ID stripping (30+ patterns) for SAP, Salesforce, Oracle, Workday, ServiceNow, Dynamics 365; custom web component awareness; virtual scrolling support; loading state detection
16
+ - **RAG-Enhanced AI Healing** — 6 knowledge sources (healing history, page objects, git changes, DOM snapshots, component docs, test specs) with TF-IDF similarity search
17
+ - **Healing Analytics & Metrics** — Strategy effectiveness tracking, per-locator healing frequency, test stability scoring (0-100), trend detection (improving/stable/degrading)
18
+ - **Smart Retry Intelligence** — Network idle wait, DOM stability detection (MutationObserver), exponential backoff with jitter, flaky test detection
19
+ - **Parallel Execution Safety** — Advisory file locking with PID tracking, stale lock detection, cross-platform support
20
+ - **Visual Verification** — Post-heal element validation (visibility, bounding box, viewport position), optional screenshot capture
21
+ - **Git Integration** — Auto-create PRs with healed locators on GitHub, GitLab, and Bitbucket; AST-based source code modification via ts-morph
22
+ - **Local Review Dashboard** — Express + WebSocket server for reviewing heals before applying
23
+ - **HTML & JSON Reports** — Detailed healing reports with strategy breakdown and confidence scores
24
+ - **CLI Setup** — `npx mindheal init` interactive setup with AI provider selection
25
+ - **Dialog Auto-Handling** — Automatic alert/confirm/prompt dismissal during healing
26
+ - **Disk-Backed Cache** — TTL-based cache with usage tracking and pattern-based lookup
27
+ - **266 Unit & Integration Tests** — Full test coverage across 17 test files
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 MindHeal Contributors
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.
package/README.md ADDED
@@ -0,0 +1,481 @@
1
+ <p align="center">
2
+ <h1 align="center">MindHeal</h1>
3
+ <p align="center"><strong>AI-powered auto-healing for Playwright tests</strong></p>
4
+ <p align="center">
5
+ <a href="https://www.npmjs.com/package/mindheal"><img src="https://img.shields.io/npm/v/mindheal.svg?style=flat-square" alt="npm version" /></a>
6
+ <a href="https://github.com/dvhiremath26/mindheal/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/mindheal.svg?style=flat-square" alt="license" /></a>
7
+ <img src="https://img.shields.io/badge/TypeScript-strict-blue?style=flat-square&logo=typescript" alt="TypeScript" />
8
+ <img src="https://img.shields.io/badge/Playwright-%3E%3D1.40-45ba4b?style=flat-square&logo=playwright" alt="Playwright" />
9
+ </p>
10
+ </p>
11
+
12
+ ---
13
+
14
+ **MindHeal** is a drop-in npm package that auto-heals broken Playwright locators at runtime. When a test step fails because an element moved, got renamed, or changed structure, MindHeal intercepts the failure, runs a pipeline of up to 10 healing strategies (including AI + RAG), and retries the action transparently — without touching your test code.
15
+
16
+ Works with **any design pattern**: Page Object Model, BDD Cucumber, Screenplay, or plain spec files.
17
+
18
+ ---
19
+
20
+ ## Quick Start
21
+
22
+ ### 1. Install
23
+
24
+ ```bash
25
+ npm install mindheal dotenv
26
+ ```
27
+
28
+ ### 2. Run the init command
29
+
30
+ ```bash
31
+ npx mindheal init
32
+ ```
33
+
34
+ An interactive prompt lets you pick your AI provider. The command then:
35
+
36
+ - Creates `tests/base.ts` (re-exports `test` and `expect` from mindheal)
37
+ - Updates all `.spec.ts` / `.test.ts` imports automatically
38
+ - Creates `.env.example` with the correct env vars for your provider
39
+ - Patches `playwright.config.ts` with `mindHealConfig()`
40
+
41
+ ### 3. Add your API key
42
+
43
+ ```bash
44
+ cp .env.example .env
45
+ # Then fill in your key, e.g. ANTHROPIC_API_KEY=sk-ant-...
46
+ ```
47
+
48
+ > **No API key?** Strategies 1–9 (Cache → Enterprise) work without one. Only strategy 10 (AI) requires a key. Or select **Ollama** during init for free local inference.
49
+
50
+ ### 4. Run your tests
51
+
52
+ ```bash
53
+ npx playwright test
54
+ ```
55
+
56
+ **Done. Your tests now self-heal.**
57
+
58
+ ---
59
+
60
+ ## How It Works
61
+
62
+ MindHeal is a **fallback-only mechanism** — zero overhead on passing tests.
63
+
64
+ ```
65
+ page.locator('.submit-btn').click()
66
+
67
+ ┌────┴────┐
68
+ │ │
69
+ PASS FAIL
70
+ │ │
71
+ Done Healing Pipeline
72
+ 1. Cache — previously healed locator?
73
+ 2. Attribute — similar id/name/data-testid?
74
+ 3. Text — similar visible text?
75
+ 4. Role — same ARIA role?
76
+ 5. CSS — similar CSS selector?
77
+ 6. XPath — similar XPath expression?
78
+ 7. Table — same table row/column?
79
+ 8. Modal — inside a dialog/popup?
80
+ 9. Enterprise — SAP/Salesforce dynamic IDs?
81
+ 10. AI + RAG — LLM with project context
82
+
83
+ First result ≥ confidence threshold
84
+
85
+ ┌────┴────┐
86
+ │ │
87
+ FOUND NOT FOUND
88
+ │ │
89
+ Retry Throw original error
90
+ action (test fails normally)
91
+ ```
92
+
93
+ MindHeal wraps `page.locator()`, `page.getByRole()`, and all 8 Playwright locator methods via an ES Proxy — no monkey-patching, no changes to your page objects.
94
+
95
+ ---
96
+
97
+ ## Key Features
98
+
99
+ | Feature | Details |
100
+ |---------|---------|
101
+ | **10 healing strategies** | Cache → Attribute → Text → Role → CSS → XPath → Table → Modal → Enterprise → AI |
102
+ | **RAG-enhanced AI** | AI strategy gets project context: past heals, page objects, git diffs, DOM snapshots |
103
+ | **Enterprise support** | SAP Fiori, Salesforce LWC, Workday, ServiceNow, Oracle, Dynamics 365 |
104
+ | **Shadow DOM & iFrames** | Recursively pierces shadow roots; wraps all frame access methods |
105
+ | **Dialog auto-handling** | Auto-dismisses `alert()`, `confirm()`, `prompt()`, `beforeunload` |
106
+ | **Local review dashboard** | Opens at `localhost:3000` to approve/reject/edit healed locators |
107
+ | **CI auto-PR** | Commits healed locators and creates a PR (GitHub, GitLab, Bitbucket) |
108
+ | **Healing analytics** | Strategy stats, fragile locator tracking, test stability scores |
109
+ | **Smart retry** | Network-idle wait, DOM stability wait, flaky vs broken detection |
110
+ | **Parallel safety** | File locking for shared resources across Playwright workers |
111
+ | **Visual verification** | Validates healed element is visible and in viewport (opt-in) |
112
+
113
+ ---
114
+
115
+ ## Configuration
116
+
117
+ Minimum config — this is all most users need:
118
+
119
+ ```ts
120
+ // playwright.config.ts
121
+ import { defineConfig } from '@playwright/test';
122
+ import { mindHealConfig } from 'mindheal';
123
+ import 'dotenv/config';
124
+
125
+ export default defineConfig({
126
+ ...mindHealConfig({
127
+ ai: {
128
+ provider: 'anthropic',
129
+ apiKey: process.env.ANTHROPIC_API_KEY!,
130
+ },
131
+ }),
132
+ testDir: './tests',
133
+ });
134
+ ```
135
+
136
+ <details>
137
+ <summary>Full configuration reference (all options with defaults)</summary>
138
+
139
+ ```ts
140
+ import type { MindHealConfig } from 'mindheal';
141
+
142
+ const config: MindHealConfig = {
143
+ // REQUIRED
144
+ ai: {
145
+ provider: 'anthropic',
146
+ apiKey: '',
147
+ model: 'claude-sonnet-4-20250514',
148
+ maxTokens: 1024,
149
+ temperature: 0.1,
150
+ baseUrl: undefined,
151
+ // Azure: azureDeploymentName, azureApiVersion
152
+ // Ollama: ollamaHost: 'http://localhost:11434'
153
+ // Bedrock: awsRegion, awsAccessKeyId, awsSecretAccessKey, awsSessionToken
154
+ },
155
+
156
+ // Healing behavior
157
+ healing: {
158
+ enabled: true,
159
+ maxRetries: 3,
160
+ strategies: ['cache', 'attribute', 'text', 'role', 'css', 'xpath', 'table', 'modal', 'enterprise', 'ai'],
161
+ confidenceThreshold: 0.7,
162
+ cacheHeals: true,
163
+ cachePath: '.mindheal/cache.json',
164
+ excludePatterns: [],
165
+ domSnapshotDepth: 3,
166
+ handleDialogs: true,
167
+ // handleDialogs: { dismissAlerts, acceptConfirms, promptResponse, logDialogs }
168
+ },
169
+
170
+ // Enterprise apps (auto-detected)
171
+ enterprise: {
172
+ enabled: true,
173
+ platform: 'auto', // 'auto' | 'salesforce' | 'sap' | 'oracle' | 'workday' | 'servicenow' | 'dynamics'
174
+ waitForLoad: true,
175
+ loadTimeout: 15000,
176
+ virtualScrolling: true,
177
+ customStableAttributes: [],
178
+ customDynamicIdPatterns: [],
179
+ },
180
+
181
+ // RAG knowledge store
182
+ rag: {
183
+ enabled: true,
184
+ storePath: '.mindheal/knowledge.json',
185
+ maxContextChunks: 5,
186
+ similarityThreshold: 0.3,
187
+ sources: ['healing-history', 'page-objects', 'git-changes', 'dom-snapshots', 'component-docs', 'test-specs'],
188
+ pageObjectPaths: ['pages', 'src/pages', 'page-objects'],
189
+ componentDocPaths: [],
190
+ },
191
+
192
+ // Analytics
193
+ analytics: {
194
+ enabled: true,
195
+ storePath: '.mindheal/analytics.json',
196
+ trackLocators: true,
197
+ trackStrategies: true,
198
+ trackTestStability: true,
199
+ maxEntries: 5000,
200
+ retentionDays: 90,
201
+ },
202
+
203
+ // Smart retry
204
+ smartRetry: {
205
+ enabled: true,
206
+ waitForNetworkIdle: true,
207
+ networkIdleTimeout: 5000,
208
+ exponentialBackoff: true,
209
+ backoffBaseDelay: 500,
210
+ backoffMaxDelay: 10000,
211
+ flakyDetection: true,
212
+ flakyThreshold: 3,
213
+ flakyStorePath: '.mindheal/flaky-tests.json',
214
+ },
215
+
216
+ // Parallel execution safety
217
+ parallel: {
218
+ enabled: true,
219
+ lockTimeout: 10000,
220
+ lockRetryInterval: 50,
221
+ staleLockThreshold: 30000,
222
+ },
223
+
224
+ // Visual verification (disabled by default — adds ~50-200ms per heal)
225
+ visualVerification: {
226
+ enabled: false,
227
+ screenshotDir: '.mindheal/screenshots',
228
+ diffThreshold: 0.1,
229
+ captureElement: true,
230
+ captureFullPage: false,
231
+ keepScreenshots: true,
232
+ },
233
+
234
+ // Git / auto-PR (only needed for CI auto-PR)
235
+ git: {
236
+ enabled: true,
237
+ provider: 'github', // 'github' | 'gitlab' | 'bitbucket'
238
+ token: '',
239
+ baseBranch: 'main',
240
+ branchPrefix: 'mindheal/auto-fix',
241
+ autoCreatePR: true,
242
+ commitMessagePrefix: 'fix(locators):',
243
+ prLabels: ['auto-heal', 'mindheal'],
244
+ prReviewers: [],
245
+ repoOwner: '', // auto-detected from git remote
246
+ repoName: '', // auto-detected from git remote
247
+ },
248
+
249
+ // Local review dashboard
250
+ reviewServer: {
251
+ enabled: 'auto', // true | false | 'auto' (local runs only)
252
+ port: 3000,
253
+ openBrowser: true,
254
+ autoCloseAfterReview: true,
255
+ },
256
+
257
+ // Reporting
258
+ reporting: {
259
+ outputDir: '.mindheal/reports',
260
+ generateHTML: true,
261
+ generateJSON: true,
262
+ },
263
+
264
+ // Logging
265
+ logging: {
266
+ level: 'info',
267
+ file: undefined,
268
+ },
269
+ };
270
+ ```
271
+
272
+ </details>
273
+
274
+ ---
275
+
276
+ ## AI Providers
277
+
278
+ 11 providers supported. The AI strategy is the **last** in the pipeline — it only runs when all deterministic strategies fail, keeping API costs minimal.
279
+
280
+ | Provider | Default Model | Env Var | Local? |
281
+ |----------|--------------|---------|--------|
282
+ | `anthropic` | `claude-sonnet-4-20250514` | `ANTHROPIC_API_KEY` | No |
283
+ | `openai` | `gpt-4o` | `OPENAI_API_KEY` | No |
284
+ | `azure-openai` | (your deployment) | `AZURE_OPENAI_API_KEY` | No |
285
+ | `gemini` | `gemini-2.0-flash` | `GEMINI_API_KEY` | No |
286
+ | `ollama` | `llama3` | None | **Yes** |
287
+ | `aws-bedrock` | `claude-3-haiku-...` | `AWS_ACCESS_KEY_ID` | No |
288
+ | `deepseek` | `deepseek-chat` | `DEEPSEEK_API_KEY` | No |
289
+ | `groq` | `llama-3.3-70b-versatile` | `GROQ_API_KEY` | No |
290
+ | `qwen` | `qwen-plus` | `QWEN_API_KEY` | No |
291
+ | `meta` | `Llama-3.3-70B-Instruct-Turbo` | `TOGETHER_API_KEY` | No |
292
+ | `perplexity` | `sonar-pro` | `PERPLEXITY_API_KEY` | No |
293
+
294
+ **Ollama (free, air-gapped):**
295
+
296
+ ```bash
297
+ ollama pull llama3 && ollama serve
298
+ ```
299
+
300
+ ```ts
301
+ mindHealConfig({
302
+ ai: {
303
+ provider: 'ollama',
304
+ apiKey: '',
305
+ model: 'llama3',
306
+ ollamaHost: process.env.OLLAMA_HOST || 'http://localhost:11434',
307
+ },
308
+ });
309
+ ```
310
+
311
+ ---
312
+
313
+ ## CI/CD Setup
314
+
315
+ In CI (`CI=true`), the review dashboard is skipped. If `git` config is provided, healed locators are committed and a PR is created automatically.
316
+
317
+ <details>
318
+ <summary>GitHub Actions example</summary>
319
+
320
+ ```yaml
321
+ - name: Run Playwright tests
322
+ env:
323
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
324
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
325
+ run: npx playwright test
326
+ ```
327
+
328
+ ```ts
329
+ // playwright.config.ts
330
+ mindHealConfig({
331
+ ai: { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY! },
332
+ git: {
333
+ enabled: true,
334
+ provider: 'github',
335
+ token: process.env.GITHUB_TOKEN!,
336
+ baseBranch: 'main',
337
+ autoCreatePR: true,
338
+ },
339
+ });
340
+ ```
341
+
342
+ </details>
343
+
344
+ ---
345
+
346
+ ## Design Pattern Compatibility
347
+
348
+ MindHeal proxies the `page` object — healing flows through any pattern that calls Playwright locators.
349
+
350
+ <details>
351
+ <summary>Page Object Model, BDD Cucumber, and plain test examples</summary>
352
+
353
+ **Page Object Model**
354
+
355
+ ```ts
356
+ // pages/login.page.ts — no changes needed
357
+ import { type Page } from '@playwright/test';
358
+
359
+ export class LoginPage {
360
+ constructor(private page: Page) {}
361
+
362
+ async login(email: string, password: string) {
363
+ await this.page.getByLabel('Email').fill(email);
364
+ await this.page.getByLabel('Password').fill(password);
365
+ await this.page.getByRole('button', { name: 'Log In' }).click();
366
+ // All locators above are auto-healed if they break
367
+ }
368
+ }
369
+
370
+ // tests/login.spec.ts
371
+ import { test } from './base'; // <-- only change needed
372
+ import { LoginPage } from '../pages/login.page';
373
+
374
+ test('user can login', async ({ page }) => {
375
+ const loginPage = new LoginPage(page);
376
+ await loginPage.login('user@test.com', 'secret');
377
+ });
378
+ ```
379
+
380
+ **BDD Cucumber**
381
+
382
+ ```ts
383
+ // support/world.ts
384
+ import { chromium } from '@playwright/test';
385
+ import { LoginPage } from '../pages/login.page';
386
+
387
+ export class CustomWorld {
388
+ async init() {
389
+ const browser = await chromium.launch();
390
+ this.page = await (await browser.newContext()).newPage();
391
+ this.loginPage = new LoginPage(this.page); // healed page flows through
392
+ }
393
+ }
394
+ ```
395
+
396
+ **Plain tests**
397
+
398
+ ```ts
399
+ import { test } from './base';
400
+
401
+ test('checkout flow', async ({ page }) => {
402
+ await page.goto('/products');
403
+ await page.getByText('Add to Cart').click();
404
+ await page.getByRole('button', { name: 'Checkout' }).click();
405
+ });
406
+ ```
407
+
408
+ </details>
409
+
410
+ ---
411
+
412
+ ## Supported Locator Methods
413
+
414
+ All 8 Playwright locator methods are intercepted across Page, Frame, and FrameLocator contexts:
415
+
416
+ `page.locator()` · `page.getByRole()` · `page.getByText()` · `page.getByTestId()` · `page.getByLabel()` · `page.getByPlaceholder()` · `page.getByAltText()` · `page.getByTitle()`
417
+
418
+ Chained locators and `frameLocator().locator()` are also supported.
419
+
420
+ ---
421
+
422
+ ## Healing Analytics
423
+
424
+ ```ts
425
+ import { HealingAnalytics } from 'mindheal';
426
+
427
+ const analytics = new HealingAnalytics(config.analytics);
428
+ analytics.load();
429
+
430
+ analytics.getOverallStats(); // { totalHeals, successRate, avgConfidence, ... }
431
+ analytics.getStrategyStats(); // ranked by success rate
432
+ analytics.getMostHealedLocators(10); // fragile locator hotspots
433
+ analytics.getUnstableTests(10); // tests with degrading stability scores
434
+ ```
435
+
436
+ ---
437
+
438
+ ## Disabling MindHeal
439
+
440
+ Change one line in `tests/base.ts`:
441
+
442
+ ```ts
443
+ // MindHeal ON
444
+ import { test, expect } from 'mindheal';
445
+
446
+ // MindHeal OFF
447
+ import { test, expect } from '@playwright/test';
448
+
449
+ export { test, expect };
450
+ ```
451
+
452
+ To uninstall: `npm uninstall mindheal` and revert `tests/base.ts`.
453
+
454
+ ---
455
+
456
+ ## Troubleshooting
457
+
458
+ | Symptom | Fix |
459
+ |---------|-----|
460
+ | `Cannot find module 'mindheal'` | Run `npm install mindheal` |
461
+ | Healing never triggers | Check `confidenceThreshold` — try lowering to `0.5` |
462
+ | AI strategy not running | Verify your API key is set and the `ai` config is correct |
463
+ | Review dashboard not opening | Check `reviewServer.port` is not in use; set `openBrowser: true` |
464
+ | Healed locator is wrong element | Enable `visualVerification: { enabled: true }` |
465
+ | Parallel workers corrupting cache | `parallel.enabled` defaults to `true` — verify no custom file locking conflicts |
466
+ | Ollama connection refused | Run `ollama serve` before tests; check `ollamaHost` matches |
467
+
468
+ ---
469
+
470
+ ## Contributing
471
+
472
+ Issues and pull requests are welcome at [dvhiremath26/mindheal](https://github.com/dvhiremath26/mindheal).
473
+
474
+ - Bug reports: [github.com/dvhiremath26/mindheal/issues](https://github.com/dvhiremath26/mindheal/issues)
475
+ - Security vulnerabilities: please open a private security advisory on GitHub rather than a public issue.
476
+
477
+ ---
478
+
479
+ ## License
480
+
481
+ MIT © [Deepak Hiremath](https://www.linkedin.com/in/deepak-hiremath-0017937a)
@@ -0,0 +1,46 @@
1
+ 'use strict';
2
+
3
+ var anthropicProvider = require('./anthropic-provider.js');
4
+ var openaiProvider = require('./openai-provider.js');
5
+ var azureOpenaiProvider = require('./azure-openai-provider.js');
6
+ var geminiProvider = require('./gemini-provider.js');
7
+ var ollamaProvider = require('./ollama-provider.js');
8
+ var bedrockProvider = require('./bedrock-provider.js');
9
+ var deepseekProvider = require('./deepseek-provider.js');
10
+ var groqProvider = require('./groq-provider.js');
11
+ var qwenProvider = require('./qwen-provider.js');
12
+ var metaProvider = require('./meta-provider.js');
13
+ var perplexityProvider = require('./perplexity-provider.js');
14
+
15
+ function createAIProvider(config) {
16
+ switch (config.provider) {
17
+ case 'anthropic':
18
+ return new anthropicProvider.AnthropicProvider(config);
19
+ case 'openai':
20
+ return new openaiProvider.OpenAIProvider(config);
21
+ case 'azure-openai':
22
+ return new azureOpenaiProvider.AzureOpenAIProvider(config);
23
+ case 'gemini':
24
+ return new geminiProvider.GeminiProvider(config);
25
+ case 'ollama':
26
+ return new ollamaProvider.OllamaProvider(config);
27
+ case 'aws-bedrock':
28
+ return new bedrockProvider.BedrockProvider(config);
29
+ case 'deepseek':
30
+ return new deepseekProvider.DeepSeekProvider(config);
31
+ case 'groq':
32
+ return new groqProvider.GroqProvider(config);
33
+ case 'qwen':
34
+ return new qwenProvider.QwenProvider(config);
35
+ case 'meta':
36
+ return new metaProvider.MetaProvider(config);
37
+ case 'perplexity':
38
+ return new perplexityProvider.PerplexityProvider(config);
39
+ default:
40
+ throw new Error(`[MindHeal] Unsupported AI provider: "${config.provider}". ` +
41
+ `Supported: anthropic, openai, azure-openai, gemini, ollama, aws-bedrock, deepseek, groq, qwen, meta, perplexity`);
42
+ }
43
+ }
44
+
45
+ exports.createAIProvider = createAIProvider;
46
+ //# sourceMappingURL=ai-provider.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ai-provider.js","sources":["../../../../src/ai/ai-provider.ts"],"sourcesContent":[null],"names":["AnthropicProvider","OpenAIProvider","AzureOpenAIProvider","GeminiProvider","OllamaProvider","BedrockProvider","DeepSeekProvider","GroqProvider","QwenProvider","MetaProvider","PerplexityProvider"],"mappings":";;;;;;;;;;;;;;AAaM,SAAU,gBAAgB,CAAC,MAAgB,EAAA;AAC/C,IAAA,QAAQ,MAAM,CAAC,QAAQ;AACrB,QAAA,KAAK,WAAW;AACd,YAAA,OAAO,IAAIA,mCAAiB,CAAC,MAAM,CAAC;AACtC,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,IAAIC,6BAAc,CAAC,MAAM,CAAC;AACnC,QAAA,KAAK,cAAc;AACjB,YAAA,OAAO,IAAIC,uCAAmB,CAAC,MAAM,CAAC;AACxC,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,IAAIC,6BAAc,CAAC,MAAM,CAAC;AACnC,QAAA,KAAK,QAAQ;AACX,YAAA,OAAO,IAAIC,6BAAc,CAAC,MAAM,CAAC;AACnC,QAAA,KAAK,aAAa;AAChB,YAAA,OAAO,IAAIC,+BAAe,CAAC,MAAM,CAAC;AACpC,QAAA,KAAK,UAAU;AACb,YAAA,OAAO,IAAIC,iCAAgB,CAAC,MAAM,CAAC;AACrC,QAAA,KAAK,MAAM;AACT,YAAA,OAAO,IAAIC,yBAAY,CAAC,MAAM,CAAC;AACjC,QAAA,KAAK,MAAM;AACT,YAAA,OAAO,IAAIC,yBAAY,CAAC,MAAM,CAAC;AACjC,QAAA,KAAK,MAAM;AACT,YAAA,OAAO,IAAIC,yBAAY,CAAC,MAAM,CAAC;AACjC,QAAA,KAAK,YAAY;AACf,YAAA,OAAO,IAAIC,qCAAkB,CAAC,MAAM,CAAC;AACvC,QAAA;AACE,YAAA,MAAM,IAAI,KAAK,CACb,wCAAwC,MAAM,CAAC,QAAQ,CAAA,GAAA,CAAK;AAC5D,gBAAA,CAAA,+GAAA,CAAiH,CAClH;;AAEP;;;;"}