digital-ai-testing-mcp 2.2.1 → 2.3.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 (97) hide show
  1. package/README.md +28 -16
  2. package/dist/api/browser-events.d.ts +48 -0
  3. package/dist/api/browser-events.d.ts.map +1 -0
  4. package/dist/api/browser-events.js +155 -0
  5. package/dist/api/browser-events.js.map +1 -0
  6. package/dist/api/browser-inspection.d.ts +21 -0
  7. package/dist/api/browser-inspection.d.ts.map +1 -1
  8. package/dist/api/browser-inspection.js +113 -20
  9. package/dist/api/browser-inspection.js.map +1 -1
  10. package/dist/api/playwright-runs.d.ts +42 -0
  11. package/dist/api/playwright-runs.d.ts.map +1 -0
  12. package/dist/api/playwright-runs.js +207 -0
  13. package/dist/api/playwright-runs.js.map +1 -0
  14. package/dist/api/reporting.d.ts.map +1 -1
  15. package/dist/api/reporting.js +4 -2
  16. package/dist/api/reporting.js.map +1 -1
  17. package/dist/api/repository.d.ts +13 -1
  18. package/dist/api/repository.d.ts.map +1 -1
  19. package/dist/api/repository.js +39 -4
  20. package/dist/api/repository.js.map +1 -1
  21. package/dist/api/test-runs.d.ts +5 -0
  22. package/dist/api/test-runs.d.ts.map +1 -1
  23. package/dist/api/test-runs.js.map +1 -1
  24. package/dist/api/webdriver.d.ts +23 -2
  25. package/dist/api/webdriver.d.ts.map +1 -1
  26. package/dist/api/webdriver.js +142 -13
  27. package/dist/api/webdriver.js.map +1 -1
  28. package/dist/index.js +1 -1
  29. package/dist/tools/boilerplate-tools.d.ts +22 -0
  30. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  31. package/dist/tools/boilerplate-tools.js +323 -44
  32. package/dist/tools/boilerplate-tools.js.map +1 -1
  33. package/dist/tools/device-group-tools.js +2 -2
  34. package/dist/tools/device-group-tools.js.map +1 -1
  35. package/dist/tools/device-tools.js +3 -3
  36. package/dist/tools/device-tools.js.map +1 -1
  37. package/dist/tools/inspection-tools.d.ts +24 -0
  38. package/dist/tools/inspection-tools.d.ts.map +1 -1
  39. package/dist/tools/inspection-tools.js +129 -13
  40. package/dist/tools/inspection-tools.js.map +1 -1
  41. package/dist/tools/meta-tools.d.ts +1 -1
  42. package/dist/tools/meta-tools.d.ts.map +1 -1
  43. package/dist/tools/meta-tools.js +3 -2
  44. package/dist/tools/meta-tools.js.map +1 -1
  45. package/dist/tools/prompt-tools.d.ts.map +1 -1
  46. package/dist/tools/prompt-tools.js +4 -0
  47. package/dist/tools/prompt-tools.js.map +1 -1
  48. package/dist/tools/reporting-tools.d.ts.map +1 -1
  49. package/dist/tools/reporting-tools.js +27 -8
  50. package/dist/tools/reporting-tools.js.map +1 -1
  51. package/dist/tools/repository-tools.d.ts.map +1 -1
  52. package/dist/tools/repository-tools.js +5 -3
  53. package/dist/tools/repository-tools.js.map +1 -1
  54. package/dist/tools/test-run-tools.d.ts.map +1 -1
  55. package/dist/tools/test-run-tools.js +107 -6
  56. package/dist/tools/test-run-tools.js.map +1 -1
  57. package/dist/tools/usage-report-tools.d.ts.map +1 -1
  58. package/dist/tools/usage-report-tools.js +6 -4
  59. package/dist/tools/usage-report-tools.js.map +1 -1
  60. package/dist/tools/web-inspection-tools.d.ts.map +1 -1
  61. package/dist/tools/web-inspection-tools.js +116 -13
  62. package/dist/tools/web-inspection-tools.js.map +1 -1
  63. package/dist/types/digital-ai.d.ts +6 -1
  64. package/dist/types/digital-ai.d.ts.map +1 -1
  65. package/dist/utils/adb-shell.d.ts +25 -0
  66. package/dist/utils/adb-shell.d.ts.map +1 -0
  67. package/dist/utils/adb-shell.js +87 -0
  68. package/dist/utils/adb-shell.js.map +1 -0
  69. package/dist/utils/credential-env.d.ts +36 -0
  70. package/dist/utils/credential-env.d.ts.map +1 -0
  71. package/dist/utils/credential-env.js +57 -0
  72. package/dist/utils/credential-env.js.map +1 -0
  73. package/dist/utils/failure-triage.d.ts +13 -0
  74. package/dist/utils/failure-triage.d.ts.map +1 -0
  75. package/dist/utils/failure-triage.js +53 -0
  76. package/dist/utils/failure-triage.js.map +1 -0
  77. package/dist/utils/locator-recommend.d.ts +27 -0
  78. package/dist/utils/locator-recommend.d.ts.map +1 -0
  79. package/dist/utils/locator-recommend.js +59 -0
  80. package/dist/utils/locator-recommend.js.map +1 -0
  81. package/dist/utils/response-formatter.d.ts +8 -0
  82. package/dist/utils/response-formatter.d.ts.map +1 -1
  83. package/dist/utils/response-formatter.js +26 -0
  84. package/dist/utils/response-formatter.js.map +1 -1
  85. package/dist/utils/usage-report-summary.d.ts +2 -0
  86. package/dist/utils/usage-report-summary.d.ts.map +1 -1
  87. package/dist/utils/usage-report-summary.js +5 -1
  88. package/dist/utils/usage-report-summary.js.map +1 -1
  89. package/package.json +13 -6
  90. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  91. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +3 -2
  92. package/resources/boilerplate/Android-Native/Python/pip-oss +1 -1
  93. package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +1 -1
  94. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  95. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +3 -2
  96. package/resources/boilerplate/iOS-Native/Python/pip-oss.txt +1 -1
  97. package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +1 -1
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
 
9
9
  Talk to your Digital.ai Testing device farm from your AI assistant. This MCP (Model Context Protocol) server connects AI clients such as Claude, GitHub Copilot and Cursor to Digital.ai Testing, so you can ask in plain language to find devices, install apps, explore an app on a real device, generate tests, run test suites, investigate failures and compare performance.
10
10
 
11
- It provides **210 tools**, **2 resources** and **7 prompts** across 27 capability areas: device management, test execution (including Espresso, XCUITest and Maestro test runs), app lifecycle, reporting and root-cause analysis, analytics, performance, project administration, interactive mobile inspection, interactive browser inspection, and more.
11
+ It provides **212 tools**, **2 resources** and **7 prompts** across 27 capability areas: device management, test execution (including Espresso, XCUITest, Maestro and Playwright test runs), app lifecycle, reporting and root-cause analysis, analytics, performance, project administration, interactive mobile inspection, interactive browser inspection, and more.
12
12
 
13
13
  ---
14
14
 
@@ -377,7 +377,7 @@ Set these as environment variables: in the client's `env` block (npm install) or
377
377
  | `MCP_REMEDIATION_DIR` | Optional | — | Debug mode only: folder to write remediation files to (overrides project detection) |
378
378
  | `REQUEST_TIMEOUT_MS` | Optional | `30000` | API request timeout in milliseconds |
379
379
  | `UPLOAD_TIMEOUT_MS` | Optional | `120000` | File upload timeout in milliseconds |
380
- | `INSPECTION_SESSION_TIMEOUT_MS` | Optional | `120000` (`240000` for `@emulator='true'` queries and automotive projection) | How long `start_inspection_session` waits for the platform to allocate a device. Emulators and simulators boot inside that request (an iOS simulator took 154 s live) |
380
+ | `INSPECTION_SESSION_TIMEOUT_MS` | Optional | `120000` (`240000` for `@emulator='true'` queries and automotive projection) | How long `start_inspection_session` waits for the platform to allocate a device. Emulators and simulators boot inside that request (an iOS simulator took 154 s live). Raising it only helps a slow boot: an emulator can also fail to boot after several minutes, so after a timeout try another model or OS version before waiting longer |
381
381
  | `USAGE_REPORT_TIMEOUT_MS` | Optional | `240000` | Wall-clock cap on one usage-report CSV fetch (`download_usage_report` / `summarize_usage_report`). An unfiltered month can be ~12 MB and take minutes to transfer; a fetch that outlives the cap returns an error that says how to narrow it |
382
382
  | `ACCESS_PROBE_TIMEOUT_MS` | Optional | `8000` | Timeout for the access-level detection call |
383
383
  | `AXE_DEVTOOLS_API_KEY` | Optional | — | Deque Axe DevTools Mobile key used by `includeAxeScan` boilerplate |
@@ -389,7 +389,7 @@ Additional `DAI_PROFILE_{NAME}_URL` / `DAI_PROFILE_{NAME}_KEY` pairs configure n
389
389
 
390
390
  ### Toolsets (reducing context size)
391
391
 
392
- All 210 tool definitions together take up roughly 70K tokens of your AI's context. If your AI client is short on context — or runs several MCP servers — set `MCP_TOOLSETS` to the areas you use, e.g. `MCP_TOOLSETS=reporting` (about 26K tokens), `MCP_TOOLSETS=inspection,authoring` (about 34K), or `MCP_TOOLSETS=core` (about 17K — only the always-loaded core in full).
392
+ All 212 tool definitions together take up roughly 70K tokens of your AI's context. If your AI client is short on context — or runs several MCP servers — set `MCP_TOOLSETS` to the areas you use, e.g. `MCP_TOOLSETS=reporting` (about 26K tokens), `MCP_TOOLSETS=inspection,authoring` (about 34K), or `MCP_TOOLSETS=core` (about 17K — only the always-loaded core in full).
393
393
 
394
394
  Nothing becomes unavailable. Tools outside the chosen toolsets are still listed, with a one-line description. When the AI calls one, the server loads that whole toolset and replies with the tool's full description and parameter guidance, then the AI calls it again — so it always sees the detailed usage guidance before the tool runs. That first call executes nothing (it is marked read-only for clients that honour tool annotations). The AI can also load toolsets up front with `enable_toolset`, whose reply lists a typed signature for every tool it loaded — so even a client that never refreshes its tool list has the exact parameter names and types. Leave `MCP_TOOLSETS` unset (the default) to load everything in full.
395
395
 
@@ -400,7 +400,7 @@ Nothing becomes unavailable. Tools outside the chosen toolsets are still listed,
400
400
  | `reporting` | Test reports, analytics, root-cause analysis, test views, coverage |
401
401
  | `performance` | Performance transactions and comparisons, NV servers |
402
402
  | `inspection` | Live device and browser inspection, Android Auto / CarPlay, remote debug |
403
- | `authoring` | Test boilerplate, Espresso / XCUITest / Maestro test runs |
403
+ | `authoring` | Test boilerplate, Espresso / XCUITest / Maestro / Playwright test runs |
404
404
  | `browsers` | Browser listing and Selenium sessions |
405
405
  | `admin` | Users, projects, backups, usage reports, POC and project workflows |
406
406
 
@@ -474,7 +474,7 @@ Once connected, talk to the server in plain language — no tool names needed:
474
474
  | Upload, install or find the latest build of an app; manage test files and iOS profiles | [Applications](docs/tools.md#applications), [Repository](docs/tools.md#repository), [Provisioning Profiles](docs/tools.md#provisioning-profiles) |
475
475
  | Explore an app or web page live with the AI | [Interactive inspection](#interactive-inspection) below |
476
476
  | Create an automated test | [Creating Tests](#creating-tests) |
477
- | Run Espresso, XCUITest or Maestro suites on the platform | [Test runs](#test-runs-espresso-xcuitest-maestro) below |
477
+ | Run Espresso, XCUITest, Maestro or Playwright suites on the platform | [Test runs](#test-runs-espresso-xcuitest-maestro) below |
478
478
  | Find out why tests failed, and track pass rates and trends | [Test Results and Root Cause Analysis](#test-results-and-root-cause-analysis) |
479
479
  | Compare performance between versions, devices or networks | [Performance Comparison Reports](#performance-comparison-reports) |
480
480
  | Export or summarize platform usage *(Cloud Admin)* | [Usage reports](#usage-reports) below |
@@ -485,14 +485,18 @@ Once connected, talk to the server in plain language — no tool names needed:
485
485
  An inspection session opens a live connection to a real device or browser so the AI can see the screen and interact with it — useful for exploring an app and capturing real element IDs before writing a test.
486
486
 
487
487
  - **Mobile** ([tools](docs/tools.md#mobile-inspection-sessions)) — Android and iOS, on both Appium Grid and Appium Server projects: screenshots, element discovery, the full gesture set, keys, app/device control (including background/resume, mid-session install from the repository and a webview-cache reset), hybrid-app webview contexts (`webview_context`), the live device log, HAR and device-log capture into the file repository, network toggles and NV network conditions, camera image injection, device diagnostics (battery, screen, dark mode, iOS accessibility audit), Android Auto / CarPlay projection, audio play/record on devices with an audio line, and mock biometric authentication. The session shares a watch-only live view URL so you can follow along. iOS behaves differently in a few places ([limitation 29](docs/limitations.md#29-ios-inspection-sessions-differ-from-android)), and Appium Grid projects support fewer commands ([limitation 18](docs/limitations.md#18-appium-grid-projects-support-fewer-commands-than-appium-server)).
488
- - **Browser** ([tools](docs/tools.md#web-inspection-sessions)) — navigate, discover elements (including inside Shadow DOM), verify CSS selectors and generate browser-neutral Selenium scripts.
488
+ - **Browser** ([tools](docs/tools.md#web-inspection-sessions)) — desktop browsers, or Chrome / Safari on a cloud phone (`mobilePlatform`): navigate, discover elements (including inside Shadow DOM), verify CSS selectors, read the console and failed network requests (`get_browser_log`; Chrome, Edge, Firefox and Opera), open staging sites with self-signed certificates (`acceptInsecureCerts`) and generate browser-neutral Selenium scripts. See [limitation 39](docs/limitations.md#39-browser-inspection-sessions-what-differs-by-browser).
489
489
  - **Remote debug** ([tools](docs/tools.md#remote-debug)) — `get_remote_debug_command` makes a cloud device appear as if it were plugged into your machine (over ADB for Android, usbmuxd for iOS), so Android Studio, Xcode and command-line ADB can use it — for example for shell commands or file push. Install the app **before** connecting (see [Troubleshooting](#common-symptoms)).
490
490
 
491
491
  Example prompts: [Interactive Inspection](docs/examples.md#interactive-inspection-ai-driven-test-building), [Android Auto / CarPlay](docs/examples.md#android-auto--carplay), [Web Browser Inspection](docs/examples.md#web-browser-inspection-ai-driven-browser-test-building).
492
492
 
493
493
  #### Test runs (Espresso, XCUITest, Maestro)
494
494
 
495
- The platform runs these suites itself: `execute_test_run` starts a run, `get_test_run_status` follows it, `cancel_test_run` stops it, and `get_test_run_command` gives a command to start it from your own machine. `generate_maestro_flow` builds a Maestro flow from structured steps. Maestro is Android-only. Espresso and Maestro runs are verified; XCUITest uses the same API but is not yet verified end to end. See [Test Runs](docs/tools.md#test-runs-espresso--xcuitest--maestro) and [example prompts](docs/examples.md#test-runs-espresso-xcuitest-maestro).
495
+ The platform runs these suites itself: `execute_test_run` starts a run, `get_test_run_status` follows it, `cancel_test_run` stops it, and `get_test_run_command` gives a command to start it from your own machine. `generate_maestro_flow` builds a Maestro flow from structured steps. Maestro is Android-only. Espresso and Maestro runs are verified; XCUITest uses the same API but is not yet verified end to end.
496
+
497
+ **Playwright** projects run through the platform's Execution Service: `execute_playwright_run` uploads the project (a folder or .zip), and the platform runs it in Microsoft's Playwright image on chromium, firefox or webkit; `get_test_run_status` and `cancel_test_run` take its run id. It needs a Cross Browser license — a run that stays queued with "Waiting for licenses" has no capacity on your cloud. See [limitation 38](docs/limitations.md#38-playwright-known-issues).
498
+
499
+ See [Test Runs](docs/tools.md#test-runs-espresso--xcuitest--maestro) and [example prompts](docs/examples.md#test-runs-espresso-xcuitest-maestro).
496
500
 
497
501
  Appium and Selenium tests are different: you run them from your own Appium or Selenium client (IDE, CI scripts), and the server manages the devices, apps, reservations and results they use.
498
502
 
@@ -502,7 +506,7 @@ Cloud Admins can export the platform's usage-report CSVs — device reservations
502
506
 
503
507
  ### All capability areas
504
508
 
505
- 210 tools across 27 capability areas. The complete per-tool reference — descriptions, filters, access requirements and usage notes — is in **[docs/tools.md](docs/tools.md)**.
509
+ 212 tools across 27 capability areas. The complete per-tool reference — descriptions, filters, access requirements and usage notes — is in **[docs/tools.md](docs/tools.md)**.
506
510
 
507
511
  | Area | Tools | Highlights |
508
512
  |---|---|---|
@@ -519,7 +523,7 @@ Cloud Admins can export the platform's usage-report CSVs — device reservations
519
523
  | [Health & Diagnostics](docs/tools.md#health--diagnostics) | 7 | Farm snapshot, iOS readiness, agent status, active sessions, reporter storage, license limits and utilization |
520
524
  | [Coverage Analytics](docs/tools.md#coverage-analytics) | 2 | Tested-vs-available device gap analysis |
521
525
  | [Reporting](docs/tools.md#reporting) | 23 | Search/filter test reports, root-cause analysis, failure summarization, stability, trends, logs, video download (byte ranges), share links, attachment download command, cleanup |
522
- | [Test Runs](docs/tools.md#test-runs-espresso--xcuitest--maestro) | 5 | Run Espresso, XCUITest and Maestro suites on the platform; status, cancel, local command; generate Maestro flows |
526
+ | [Test Runs](docs/tools.md#test-runs-espresso--xcuitest--maestro) | 6 | Run Espresso, XCUITest, Maestro and Playwright suites on the platform; status, cancel, local command; generate Maestro flows |
523
527
  | [Test Views](docs/tools.md#test-views) | 7 | Dashboard view groups |
524
528
  | [Transactions & Performance](docs/tools.md#transactions--performance) | 4 | CPU/memory/battery/Speed Index analytics |
525
529
  | [Agents](docs/tools.md#agents) | 2 | Host machine status *(Cloud Admin)* |
@@ -532,7 +536,7 @@ Cloud Admins can export the platform's usage-report CSVs — device reservations
532
536
  | [Mobile Inspection Sessions](docs/tools.md#mobile-inspection-sessions) | 30 | AI-driven live device interaction — screenshots, element discovery, full gesture set, keys, app/device control, webview contexts, device log, HAR/log capture, network, camera injection, Android Auto / CarPlay projection, audio play/record, mock biometric authentication |
533
537
  | [Web Inspection Sessions](docs/tools.md#web-inspection-sessions) | 8 | AI-driven live browser interaction — navigate, Shadow DOM element discovery, CSS selector verification, browser-neutral Selenium script generation |
534
538
  | [Performance Comparison](docs/tools.md#performance-comparison) | 4 | Two-set Speed Index comparison with confound detection, MAD outlier exclusion, and fresh-sample generation |
535
- | [Usage Reports](docs/tools.md#usage-reports) | 3 | Platform usage-report CSV export and in-memory aggregation — device reservations, users/devices/browser usage, user statistics, license usage; multi-section CSVs with a User Tag column, 2-year retention (platform 25.9+); large unfiltered exports run only after you explicitly agree (`confirmLargeExport`) *(Cloud Admin)* |
539
+ | [Usage Reports](docs/tools.md#usage-reports) | 3 | Platform usage-report CSV export and in-memory aggregation — device reservations, users/devices/browser usage, user statistics, license usage; multi-section CSVs with User Tag, Device Tag and Device Group columns (tag/group lists are split when grouping), 2-year retention (platform 25.9+); large unfiltered exports run only after you explicitly agree (`confirmLargeExport`) *(Cloud Admin)* |
536
540
  | [Resources & Prompts](docs/tools.md#resources--prompts) | — | 2 ambient resources, 7 guided prompts |
537
541
 
538
542
  [↑ Back to top](#table-of-contents)
@@ -561,7 +565,7 @@ The server supports two ways of creating a test, for both mobile and web, and th
561
565
 
562
566
  ### Mobile app tests (`get_test_boilerplate`)
563
567
 
564
- Generates a complete, pre-configured Appium test project. The Digital.ai server URL and access key are filled in from the active connection profile — switch profiles with `switch_environment` first if you want the script to carry a project-scoped key instead of your admin key.
568
+ Generates a complete, pre-configured Appium test project. The Digital.ai server URL is filled in from the active connection profile. The generated files contain **no access key**: they read it from the `DIGITAL_AI_ACCESS_KEY` environment variable and stop with a clear message if it is unset (a key-free `.env.example` lists what to set). Use a project-scoped key there rather than your admin key, and store it as a secret in CI.
565
569
 
566
570
  **Recommended workflow** for building a new test:
567
571
 
@@ -587,7 +591,7 @@ Generates a complete, pre-configured Appium test project. The Digital.ai server
587
591
  | `platform` | `android` \| `ios` | _(required)_ |
588
592
  | `language` | `java-junit5` \| `java-testng` \| `nodejs` \| `python` \| `robot` (Appium Server projects only) | _(required)_ |
589
593
  | `appId` | Numeric app ID from `list_applications` | Recommended |
590
- | `deviceCategory` | `PHONE` \| `TABLET` | `PHONE` |
594
+ | `deviceCategory` | `PHONE` \| `TABLET` \| `FOLDABLE` (platform 26.10+; a foldable is never matched by `PHONE`) | `PHONE` |
591
595
  | `testName` | Any string | `"My First Mobile Test"` |
592
596
  | `packageName` | Android package name (e.g. `com.mycompany.app`) | _(optional)_ |
593
597
  | `mainActivity` | Android main activity (e.g. `.MainActivity`) | _(optional)_ |
@@ -605,6 +609,10 @@ Generates a complete, pre-configured Appium test project. The Digital.ai server
605
609
  | `appiumVersion` | Appium Server version, e.g. `"2.18.0"` (Appium Server projects; not with `includeAxeScan`) | platform default |
606
610
  | `newSessionWaitTimeout` | Seconds (10–3600) to wait for a free matching device before failing with the platform's reason | _(optional)_ |
607
611
  | `reportKeys` | Custom report columns, e.g. `{"build": "1.4.0"}` — find the runs later with a `list_test_reports` filter | _(optional)_ |
612
+ | `appReset` | `reinstall` (the platform reinstalls the app at every session start) \| `keep-data` (launch the installed app, keep its data) — Appium Server projects | `reinstall` |
613
+ | `deviceLanguage` | e.g. `en_US` — sets `appium:language` + `appium:locale`. iOS: the app, for this session; **Android: the whole device, and it stays changed** — Appium Server projects | _(optional)_ |
614
+ | `autoAcceptAlerts` | `true` — iOS accepts every native alert as it appears (also hides alerts a test should check) — Appium Server projects | _(off)_ |
615
+ | `platformOptions` | `releaseDevice`, `reservationDuration`, `devicePool`, `commandScreenshot`, `dontGoHomeOnQuit` → `digitalai:*` capabilities — Appium Server projects | _(optional)_ |
608
616
  | `outputFormat` | `json` \| `human` | `json` |
609
617
 
610
618
  </details>
@@ -644,7 +652,7 @@ The agent JAR is **not** shipped with this server. By default it is downloaded f
644
652
 
645
653
  ### Web tests (`get_web_test_boilerplate`)
646
654
 
647
- Generates a complete, pre-configured Selenium test project for browser testing. The Digital.ai server URL and access key are filled in from the active connection profile.
655
+ Generates a complete, pre-configured Selenium test project for browser testing. The Digital.ai server URL is filled in from the active connection profile; the access key is read from the `DIGITAL_AI_ACCESS_KEY` environment variable, never written into the files.
648
656
 
649
657
  **Recommended workflow** for building a new web test:
650
658
 
@@ -660,6 +668,8 @@ Generates a complete, pre-configured Selenium test project for browser testing.
660
668
 
661
669
  **Browser-neutral by default:** when `targetBrowser` is omitted, the generated script reads the browser name at runtime from the `BROWSER` environment variable, so the same script runs on Chrome, Firefox, Microsoft Edge, Safari and Opera without changes (Robot Framework: every browser except Opera, which SeleniumLibrary cannot drive) — just change the variable or your CI matrix. Specify `targetBrowser` only when you need browser-specific options (e.g. Safari-only session setup).
662
670
 
671
+ **Playwright (experimental):** `language: "playwright"` generates a Playwright Test project that drives Chrome or Edge on the Digital.ai Selenium agent — `npm install`, then `npx playwright test`, with no local browser. This route is an experimental platform feature, and the Digital.ai report shows Passed even when a test fails, so read the Playwright report (see [limitation 38](docs/limitations.md#38-playwright-known-issues)).
672
+
663
673
  **Shadow DOM support:** with `always`, the generated script includes a `shadowQuery(host, cssSelector)` helper; with `auto` (the default), it is included only while a browser inspection session is open in the MCP server; `never` omits it. The helper reaches into shadow roots using `executeScript`. Use it for apps built with Web Components, Lit, Polymer or other shadow-DOM frameworks. `get_page_dom` detects shadow DOM automatically during inspection and reports `hasShadowDom: true` when present.
664
674
 
665
675
  <details>
@@ -667,12 +677,13 @@ Generates a complete, pre-configured Selenium test project for browser testing.
667
677
 
668
678
  | Parameter | Values | Default |
669
679
  |---|---|---|
670
- | `language` | `java-junit5` \| `java-testng` \| `nodejs` \| `python` \| `robot` (Robot Framework + SeleniumLibrary) | _(required)_ |
680
+ | `language` | `java-junit5` \| `java-testng` \| `nodejs` \| `python` \| `robot` (Robot Framework + SeleniumLibrary) \| `playwright` (experimental; Chrome / Edge) | _(required)_ |
671
681
  | `url` | URL of the page being tested | _(optional)_ |
672
682
  | `testName` | Any string | `"WebTest"` |
673
683
  | `targetBrowser` | `chrome` \| `firefox` \| `MicrosoftEdge` \| `safari` \| `opera` (names as `list_available_browsers` returns them; `edge` is accepted for `MicrosoftEdge`) | _(optional)_ |
674
684
  | `shadowDomSupport` | `auto` \| `always` \| `never` | `auto` |
675
685
  | `confirmSelectorsVerified` | `true` \| `false` | _(optional)_ |
686
+ | `acceptInsecureCerts` | `true` for a site with a self-signed, expired or untrusted-CA certificate | _(optional)_ |
676
687
  | `outputFormat` | `json` \| `human` | `json` |
677
688
 
678
689
  </details>
@@ -965,7 +976,7 @@ On Windows with Docker, this usually means the `--env-file` path was stored with
965
976
  Run this sequence:
966
977
 
967
978
  ```
968
- 1. get_server_info — confirm tool count (expect 210; 211 with MCP_DEBUG_MODE=true) and active profile
979
+ 1. get_server_info — confirm tool count (expect 212; 213 with MCP_DEBUG_MODE=true) and active profile
969
980
  2. check_workflow_readiness — which dependency tools are present or missing
970
981
  3. check_connectivity — confirm the backend API is reachable
971
982
  ```
@@ -975,7 +986,7 @@ Run this sequence:
975
986
  ```json
976
987
  {
977
988
  "allWorkflowsReady": true,
978
- "registeredToolCount": 210,
989
+ "registeredToolCount": 212,
979
990
  "workflows": {
980
991
  "create_poc": { "ready": true, "missingRead": [], "missingWrite": [] },
981
992
  "setup_project": { "ready": true, "missingRead": [], "missingWrite": [] }
@@ -1081,6 +1092,7 @@ The ones you're most likely to run into:
1081
1092
  5. **Usage reports go back 2 years** (platform 25.9+), and large unfiltered exports need your explicit approval. See [limitation 21](docs/limitations.md#21-usage-reports-2-year-retention-large-exports).
1082
1093
  6. **There's no way to disable or lock a user.** Removing access for a user created only for a POC means deleting the account — which is why `close_poc` asks for confirmation per user.
1083
1094
  7. **Deleting test reports with a project-level key depends on a per-project setting** (`allowUsersDeleteTests`). Cloud Admin can always delete. When the setting is off, the tools refuse up front for a Project Admin and explain how to get it enabled; a Project User cannot read the setting, so the platform returns its own 403.
1095
+ 8. **Playwright needs a Cross Browser license, and its Selenium-agent route is experimental.** An `execute_playwright_run` job without free capacity stays queued with "Waiting for licenses". Projects generated for the Selenium agent run on Chrome and Edge only, and the Digital.ai report shows Passed even when a test failed — read the Playwright report. See [limitation 38](docs/limitations.md#38-playwright-known-issues).
1084
1096
 
1085
1097
  See [docs/limitations.md](docs/limitations.md) for the full list.
1086
1098
 
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Console and network capture for browser inspection sessions over WebDriver BiDi (platform 25.11+).
3
+ *
4
+ * Verified live 2026-11-12 (uscloud): with `webSocketUrl: true` the session capabilities carry
5
+ * `wss://<cloud>/selenium-<n>/bidi/<session>`; `session.subscribe` to log.entryAdded / network.responseCompleted /
6
+ * network.fetchError delivered console.error/info, an uncaught exception and a 404 on Chrome 158, Firefox 160,
7
+ * Edge 157 and Opera 138. Safari with `webSocketUrl: true` never answered the session request (>120 s) — never ask
8
+ * for BiDi there. The socket needs no credential beyond the URL itself.
9
+ *
10
+ * Only failures are buffered for network traffic (status >= 400 or a fetch error); successful requests are counted.
11
+ * The buffer keeps the newest MAX_EVENTS entries.
12
+ */
13
+ export declare const BIDI_BROWSERS: ReadonlySet<string>;
14
+ export declare const MAX_EVENTS = 500;
15
+ export interface BrowserEvent {
16
+ kind: 'console' | 'javascript' | 'network';
17
+ level: string;
18
+ text: string;
19
+ url?: string;
20
+ status?: number;
21
+ method?: string;
22
+ time: number;
23
+ }
24
+ /** Turn one BiDi message into an event, 'ok-request' for a successful network response, or null to ignore. */
25
+ export declare function normalizeBidiMessage(raw: string, now?: number): BrowserEvent | 'ok-request' | null;
26
+ /** Connect and subscribe. Resolves to null when capture is running, else the reason it is not. Never throws. */
27
+ export declare function startBrowserEventCapture(handle: string, wsUrl: string, timeoutMs?: number): Promise<string | null>;
28
+ export declare function hasBrowserEventCapture(handle: string): boolean;
29
+ export interface BrowserEventQuery {
30
+ kind?: 'all' | 'console' | 'network';
31
+ errorsOnly?: boolean;
32
+ clear?: boolean;
33
+ maxEntries?: number;
34
+ }
35
+ export interface BrowserEventResult {
36
+ events: BrowserEvent[];
37
+ matched: number;
38
+ buffered: number;
39
+ dropped: number;
40
+ okRequests: number;
41
+ socketClosed?: string;
42
+ }
43
+ /** Filter and return captured events (newest last); `clear` empties the buffer after reading. Null if not capturing. */
44
+ export declare function readBrowserEvents(handle: string, q?: BrowserEventQuery): BrowserEventResult | null;
45
+ export declare function stopBrowserEventCapture(handle: string): void;
46
+ /** Test seam: register a capture whose socket is a stub, so readBrowserEvents can be exercised offline. */
47
+ export declare function injectBrowserEventsForTests(handle: string, events: BrowserEvent[], okRequests?: number): void;
48
+ //# sourceMappingURL=browser-events.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"browser-events.d.ts","sourceRoot":"","sources":["../../src/api/browser-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAA4D,CAAC;AAC3G,eAAO,MAAM,UAAU,MAAM,CAAC;AAG9B,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAaD,8GAA8G;AAC9G,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,YAAY,GAAG,YAAY,GAAG,IAAI,CA+BtG;AAED,gHAAgH;AAChH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqCxH;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wHAAwH;AACxH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAE,iBAAsB,GAAG,kBAAkB,GAAG,IAAI,CAkBtG;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAK5D;AAED,2GAA2G;AAC3G,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,UAAU,SAAI,GAAG,IAAI,CAExG"}
@@ -0,0 +1,155 @@
1
+ /**
2
+ * Console and network capture for browser inspection sessions over WebDriver BiDi (platform 25.11+).
3
+ *
4
+ * Verified live 2026-11-12 (uscloud): with `webSocketUrl: true` the session capabilities carry
5
+ * `wss://<cloud>/selenium-<n>/bidi/<session>`; `session.subscribe` to log.entryAdded / network.responseCompleted /
6
+ * network.fetchError delivered console.error/info, an uncaught exception and a 404 on Chrome 158, Firefox 160,
7
+ * Edge 157 and Opera 138. Safari with `webSocketUrl: true` never answered the session request (>120 s) — never ask
8
+ * for BiDi there. The socket needs no credential beyond the URL itself.
9
+ *
10
+ * Only failures are buffered for network traffic (status >= 400 or a fetch error); successful requests are counted.
11
+ * The buffer keeps the newest MAX_EVENTS entries.
12
+ */
13
+ export const BIDI_BROWSERS = new Set(['chrome', 'MicrosoftEdge', 'firefox', 'opera']);
14
+ export const MAX_EVENTS = 500;
15
+ const SUBSCRIBE_EVENTS = ['log.entryAdded', 'network.responseCompleted', 'network.fetchError'];
16
+ const captures = new Map();
17
+ /** Turn one BiDi message into an event, 'ok-request' for a successful network response, or null to ignore. */
18
+ export function normalizeBidiMessage(raw, now = Date.now()) {
19
+ let msg;
20
+ try {
21
+ msg = JSON.parse(raw);
22
+ }
23
+ catch {
24
+ return null;
25
+ }
26
+ const p = msg.params ?? {};
27
+ const time = typeof p.timestamp === 'number' ? p.timestamp : now;
28
+ if (msg.method === 'log.entryAdded') {
29
+ const frame = p.stackTrace?.callFrames?.[0];
30
+ const where = frame?.url ? `${frame.url}${frame.lineNumber != null ? `:${frame.lineNumber + 1}` : ''}` : undefined;
31
+ return {
32
+ kind: p.type === 'javascript' ? 'javascript' : 'console',
33
+ level: String(p.level ?? 'info'),
34
+ text: String(p.text ?? ''),
35
+ url: where,
36
+ time,
37
+ };
38
+ }
39
+ if (msg.method === 'network.responseCompleted') {
40
+ const status = Number(p.response?.status);
41
+ if (!(status >= 400))
42
+ return 'ok-request';
43
+ return { kind: 'network', level: 'error', text: `${status} ${p.response?.statusText ?? ''}`.trim(), url: p.request?.url, status, method: p.request?.method, time };
44
+ }
45
+ if (msg.method === 'network.fetchError') {
46
+ return { kind: 'network', level: 'error', text: String(p.errorText ?? 'request failed'), url: p.request?.url, method: p.request?.method, time };
47
+ }
48
+ return null;
49
+ }
50
+ /** Connect and subscribe. Resolves to null when capture is running, else the reason it is not. Never throws. */
51
+ export async function startBrowserEventCapture(handle, wsUrl, timeoutMs = 10_000) {
52
+ if (typeof WebSocket === 'undefined')
53
+ return 'this Node.js runtime has no WebSocket (Node 22+ needed)';
54
+ let socket;
55
+ try {
56
+ socket = new WebSocket(wsUrl);
57
+ }
58
+ catch (e) {
59
+ return `could not open the BiDi socket: ${e.message}`;
60
+ }
61
+ const cap = { socket, events: [], dropped: 0, okRequests: 0, subscribed: false };
62
+ return new Promise((resolve) => {
63
+ const timer = setTimeout(() => { try {
64
+ socket.close();
65
+ }
66
+ catch { /* ignore */ } resolve(`the BiDi socket did not answer within ${Math.round(timeoutMs / 1000)} s`); }, timeoutMs);
67
+ socket.onerror = () => { clearTimeout(timer); if (!cap.subscribed)
68
+ resolve('the BiDi socket refused the connection'); };
69
+ socket.onclose = () => {
70
+ cap.closedReason = cap.closedReason ?? 'the browser closed the BiDi socket';
71
+ // Closed before the subscribe reply (no error event): answer now instead of holding the session start for the timeout.
72
+ if (!cap.subscribed) {
73
+ clearTimeout(timer);
74
+ resolve('the BiDi socket closed before the subscription was confirmed');
75
+ }
76
+ };
77
+ socket.onopen = () => socket.send(JSON.stringify({ id: 1, method: 'session.subscribe', params: { events: SUBSCRIBE_EVENTS } }));
78
+ socket.onmessage = (m) => {
79
+ const raw = String(m.data);
80
+ if (!cap.subscribed) {
81
+ try {
82
+ const j = JSON.parse(raw);
83
+ if (j.id === 1) {
84
+ clearTimeout(timer);
85
+ if (j.type === 'error' || j.error) {
86
+ try {
87
+ socket.close();
88
+ }
89
+ catch { /* ignore */ }
90
+ resolve(`session.subscribe failed: ${j.message ?? j.error}`);
91
+ return;
92
+ }
93
+ cap.subscribed = true;
94
+ captures.set(handle, cap);
95
+ resolve(null);
96
+ return;
97
+ }
98
+ }
99
+ catch { /* not the subscribe reply */ }
100
+ }
101
+ const ev = normalizeBidiMessage(raw);
102
+ if (ev === 'ok-request')
103
+ cap.okRequests++;
104
+ else if (ev) {
105
+ cap.events.push(ev);
106
+ if (cap.events.length > MAX_EVENTS) {
107
+ cap.events.shift();
108
+ cap.dropped++;
109
+ }
110
+ }
111
+ };
112
+ });
113
+ }
114
+ export function hasBrowserEventCapture(handle) {
115
+ return captures.has(handle);
116
+ }
117
+ /** Filter and return captured events (newest last); `clear` empties the buffer after reading. Null if not capturing. */
118
+ export function readBrowserEvents(handle, q = {}) {
119
+ const cap = captures.get(handle);
120
+ if (!cap)
121
+ return null;
122
+ const kind = q.kind ?? 'all';
123
+ const matched = cap.events.filter((e) => (kind === 'all' || (kind === 'network' ? e.kind === 'network' : e.kind !== 'network')) &&
124
+ (!q.errorsOnly || e.level === 'error'));
125
+ const max = Math.max(1, q.maxEntries ?? 50);
126
+ const result = {
127
+ events: matched.slice(-max),
128
+ matched: matched.length,
129
+ buffered: cap.events.length,
130
+ dropped: cap.dropped,
131
+ okRequests: cap.okRequests,
132
+ ...(cap.socket.readyState === 3 ? { socketClosed: cap.closedReason ?? 'closed' } : {}),
133
+ };
134
+ if (q.clear) {
135
+ cap.events = [];
136
+ cap.dropped = 0;
137
+ cap.okRequests = 0;
138
+ }
139
+ return result;
140
+ }
141
+ export function stopBrowserEventCapture(handle) {
142
+ const cap = captures.get(handle);
143
+ if (!cap)
144
+ return;
145
+ captures.delete(handle);
146
+ try {
147
+ cap.socket.close();
148
+ }
149
+ catch { /* already closed */ }
150
+ }
151
+ /** Test seam: register a capture whose socket is a stub, so readBrowserEvents can be exercised offline. */
152
+ export function injectBrowserEventsForTests(handle, events, okRequests = 0) {
153
+ captures.set(handle, { socket: { readyState: 1, close() { } }, events: [...events], dropped: 0, okRequests, subscribed: true });
154
+ }
155
+ //# sourceMappingURL=browser-events.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"browser-events.js","sourceRoot":"","sources":["../../src/api/browser-events.ts"],"names":[],"mappings":"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"}
@@ -3,8 +3,29 @@ export interface BrowserSessionOptions {
3
3
  browserName: string;
4
4
  os?: string;
5
5
  reportName?: string;
6
+ /** W3C acceptInsecureCerts — load sites with self-signed/untrusted certificates (verified live 2026-11-12 on
7
+ * Chrome, Firefox, MicrosoftEdge and Safari against self-signed.badssl.com). */
8
+ acceptInsecureCerts?: boolean;
9
+ /** Capture console messages, uncaught JS errors and failed requests over WebDriver BiDi (default true where the
10
+ * browser supports it — see BIDI_BROWSERS; never on Safari, which hangs the session request). */
11
+ captureEvents?: boolean;
12
+ /** Mobile browser on a cloud phone: Chrome on Android, Safari on iOS (verified live 2026-11-12 on Appium Server and
13
+ * Appium Grid projects — navigate/title/find/text/source/screenshot all work; Grid sessions answer in JWP). */
14
+ mobile?: {
15
+ platform: 'android' | 'ios';
16
+ deviceQuery?: string;
17
+ region?: string;
18
+ };
6
19
  }
20
+ /** Mobile browser sessions can take ~25–55 s to allocate a phone (live); give the platform up to 150 s. */
21
+ export declare const MOBILE_BROWSER_TIMEOUT_MS = 180000;
7
22
  export declare function createBrowserInspectionSession(opts: BrowserSessionOptions): Promise<InspectionSession>;
23
+ /**
24
+ * A site with a self-signed / untrusted certificate (verified live 2026-11-12 against self-signed.badssl.com):
25
+ * Firefox refuses the navigation with "insecure certificate"; Chrome and Edge load a page titled "Privacy error" and
26
+ * Safari one titled "This Connection Is Not Private", with no WebDriver error. Returns guidance, or null.
27
+ */
28
+ export declare function certificateWarning(errorOrTitle: string | null | undefined): string | null;
8
29
  export declare function navigateTo(handle: string, url: string): Promise<void>;
9
30
  export declare function getCurrentUrl(handle: string): Promise<string>;
10
31
  export interface PageDomNode {
@@ -1 +1 @@
1
- {"version":3,"file":"browser-inspection.d.ts","sourceRoot":"","sources":["../../src/api/browser-inspection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAgChE,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CA8E5B;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiC3E;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,WAAW,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AA8DD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAChD,cAAc,UAAQ,GACrB,OAAO,CAAC,aAAa,CAAC,CA6DxB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAgB,yBAAyB,IAAI,iBAAiB,EAAE,CAE/D"}
1
+ {"version":3,"file":"browser-inspection.d.ts","sourceRoot":"","sources":["../../src/api/browser-inspection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAiChE,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;qFACiF;IACjF,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;sGACkG;IAClG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;oHACgH;IAChH,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,SAAS,GAAG,KAAK,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF;AAED,2GAA2G;AAC3G,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAOjD,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CA2H5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAOzF;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmD3E;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,WAAW,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AA8DD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAM,GAAG,QAAQ,GAAG,OAAgB,EAChD,cAAc,UAAQ,GACrB,OAAO,CAAC,aAAa,CAAC,CA6DxB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GACrC,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAgB,yBAAyB,IAAI,iBAAiB,EAAE,CAE/D"}