@interopio/iocd-cli 0.0.92 → 1.0.1

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/configuration.md

@@ -0,0 +1,30 @@
+# Configuration
+
+Read `tests/wdio.config.ts` — it composes `IOCDBaseConfiguration` + `IOCDService()`, defines one
+`platform-wdio` capability, and sets these values:
+
+| Value | Meaning |
+|-------|---------|
+| `BINARY_PATH` | Executable from the `iocd` component; supplied by `iocd test`. Keep it. |
+| `WDIO_ROOT_DIR` / `WDIO_TESTS_ROOT` | Absolute paths to the test package and to `tests/tests/`. |
+| `iocd:options.configOverrides` | Extra platform config (absolute paths) applied only to tests. |
+| `iocd:options.ioInitOptions` | APIs + optional `libraries` used to build the test API. |
+
+`config/system.json` registers `tests/tests/config/apps.json` as a path app store and isolates
+`folders.userData` to `tests/user-data` (disposable — never commit it or reuse its state).
+
+## Add an optional IO library
+
+1. Add the package to `tests/package.json`.
+2. Add its module specifier to `iocd:options.ioInitOptions.libraries` in `tests/wdio.config.ts`.
+3. Use it via `browser.io()` (optional sub-APIs need `!`).
+
+## Runners
+
+`platform-wdio` is the default (specs run Node-side and drive the app remotely). `platform-window`,
+`platform-node`, and `standalone` are specialized — use only when asked, and read the service README.
+
+## CI
+
+Add an explicit `npm test` step on a Windows/macOS runner with the seed dependencies and the `iocd`
+component installed and the license from CI secrets. Never publish the license or `user-data`.

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/models.md

@@ -0,0 +1,52 @@
+# Built-in IOCD UI Models
+
+`@interopio/wdio-iocd-service/models` exports page objects for built-in web UI owned by IOCD. Use
+them for Web Groups, captions, tabs, Channel Selectors, and similar platform surfaces. Use normal
+WebdriverIO selectors for UI owned by the client app.
+
+Models hide generated element IDs and DOM structure behind semantic operations such as
+`group.switchTo()`, `group.frames.waitForCount()`, `tab.close()`, and `waitForDisplayed()`. They also
+handle the WebDriver context and waits expected by the built-in surface. Prefer an available model
+over copying internal IOCD selectors into a spec.
+
+## Current Generated Version
+
+The generated test package currently pins `@interopio/wdio-iocd-service@1.0.0-next.2`. Its
+`@interopio/wdio-iocd-service/models` subpath exports:
+
+| Area | Models and types |
+| --- | --- |
+| Group and frames | `Group`, `Frame`, `WebGroupElement` |
+| Captions and tabs | `CaptionBar`, `Caption`, `Editor`, `MoveArea`, `TabBar`, `TabHeader`, `Tab`, `Tabs`, `PinnedTabs` |
+| Caption controls | `ChannelSelector`, `CloseButton`, `HtmlButtons`, `ButtonsContainer`, `StandardButton`, `StandardButtons`, `CustomButton`, `CustomButtons` |
+| Sizing and snapping | `SizingBorderGroup`, `SizingBorderOrientation`, `SizingBorder`, `SizingBorderType`, `ApproachingMarker`, and the `NeighborFrames` type |
+
+For example:
+
+```ts
+import { Group } from "@interopio/wdio-iocd-service/models";
+
+const group = new Group(window.groupId!);
+const [frame] = await group.frames.waitForCount(1);
+
+await group.switchTo();
+await frame.captionBar.channelSelector.waitForDisplayed();
+await frame.captionBar.channelSelector.click();
+```
+
+## Version Rule
+
+The installed package is the source of truth. Before using a model, read:
+
+```text
+tests/node_modules/@interopio/wdio-iocd-service/dist/models/index.d.ts
+```
+
+Do not copy a model import from another repository or a newer service release without checking that
+it exists locally. Newer versions may add models such as `ChannelSelectorPopup`, `PlatformDialog`,
+`ModalsDialog`, or `Alert`; those names aren't exported by the version currently generated in the
+seed.
+
+Models reduce direct coupling to built-in markup, but remain coupled to the matching Desktop and
+service versions. If no suitable model is exported, prefer a stable `data-testid`, role, or other
+semantic selector and keep the version-sensitive selector in one local page object.

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/setup.md

@@ -0,0 +1,62 @@
+# Setup
+
+Run all setup commands from the seed root.
+
+## New seed project
+
+Tests are included automatically. Complete the seed setup, then run the suite:
+
+```bash
+npm install
+npm run setup
+npm test
+```
+
+On the first run the CLI installs the nested test package's dependencies, resolves the executable
+from the configured `iocd` component, and passes its path to WebdriverIO via `BINARY_PATH`. If the
+executable isn't available yet, start the seed once with `npm run dev`, close it, then run `npm test`
+(the service launches and manages its own platform instance). The CLI also makes
+`config/iocd.license.key` available to the test platform — keep the license out of specs, config,
+logs, and source control.
+
+## Missing test infrastructure
+
+If the test package is absent, scaffold it:
+
+```bash
+npx iocd test setup
+```
+
+This runs the seed's own `@interopio/iocd-cli` dependency, so the scaffold matches the installed CLI
+version. Fall back to `npx @interopio/iocd-cli@latest test setup` only when the seed doesn't depend
+on the CLI. Setup creates the test package and the agent skill, installs the test dependencies, and validates the
+setup with the TypeScript compiler. On failure it removes the files it created.
+
+## Replacing an existing test package
+
+The CLI never overwrites or migrates an existing test directory. To replace one:
+
+1. Inspect it for specs, assets, app definitions, config, scripts, or dependencies to keep.
+2. Get explicit user approval, then back up or remove the directory.
+3. Run `test setup` from the seed root.
+4. Transfer the required user-authored files and adapt them to the current configuration.
+5. Type-check the package and run the transferred specs one at a time.
+
+## Layout
+
+```text
+tests/                         # test package (Node.js)
+├── package.json
+├── tsconfig.json
+├── wdio.config.ts             # WebdriverIO + IOCDService config (platform-wdio runner)
+├── config/system.json         # platform overrides used only by tests
+└── tests/
+    ├── assets/applications/   # static fixture app HTML
+    ├── common/iocd.ts         # waitFor helper
+    ├── config/apps.json       # fixture app definitions (registered as a path app store)
+    └── *.spec.ts              # specifications
+```
+
+Specs are resolved from the test package, so `npm test -- --spec ./tests/x.spec.ts` runs
+`tests/tests/x.spec.ts`. `system.json` also points `folders.userData` at a disposable
+`tests/user-data`, so test runs never touch the developer's normal platform profile.

package/dist/templates/tests/.agents/skills/iocd-wdio-testing/references/troubleshooting.md

@@ -0,0 +1,66 @@
+# Troubleshooting
+
+## Missing platform executable
+
+Ensure the configured `iocd` component is installed: run `npm run setup`, or start the seed once with
+`npm run dev` and close it before `npm test` (the service starts its own instance).
+
+If `iocd test` searches for an executable named after the seed's `productName`, but the installed
+component still has its default `io.Connect Desktop` name, run `npm run dev` once. Development
+preparation applies the seed branding and creates the executable path that the test command expects;
+close that development instance before rerunning the tests.
+
+## License prompt or failure
+
+Run from the seed root through `npm test` so the CLI can use `config/iocd.license.key`. In CI, supply
+the license via secrets. Never hard-code a license in a spec or fixture.
+
+## Startup timeout
+
+Temporarily set `iocd:options.enableLogging: true` in `tests/wdio.config.ts` and read the platform
+output. Check for invalid config/app paths, license failures, gateway port conflicts (the generated
+`config/system.json` pins the test gateway to port 8385), and stale test user-data before raising
+`startupTimeoutMs`.
+
+## Missing IO API
+
+If `browser.io()` reports the API is unavailable, ensure it's called inside a runtime hook or test,
+not at module or `describe` scope. If an optional API such as `io.workspaces` is missing, verify its
+package is in `tests/package.json` and its module specifier is in `ioInitOptions.libraries`.
+
+## `no such window` after closing UI
+
+Closing the popup, dialog, preview, or utility window that currently owns the WebDriver context can
+leave the session attached to a dead handle. Later commands — including commands in the next test —
+then fail with `no such window` even though other windows are still open.
+
+After closing the active temporary window, switch to a known live IOCD window with
+`browser.switchById()` when its ID is available. Otherwise, park the session on any surviving raw
+WebDriver handle:
+
+```ts
+import { browser } from "@wdio/globals";
+
+async function parkOnAnyWindow(): Promise<void> {
+	for (const handle of await browser.getWindowHandles()) {
+		try {
+			await browser.switchToWindow(handle);
+			return;
+		} catch {
+			// The handle may have disappeared while the list was being inspected.
+		}
+	}
+
+	throw new Error("No open WebDriver windows remain.");
+}
+```
+
+Call the recovery in `finally` or cleanup immediately after dismissing the temporary window. Keep it
+local to tests that own such windows; don't add it to every generated spec preemptively.
+
+## Flaky UI test
+
+Run only the failing spec, replace fixed delays with observable waits, subscribe before actions, and
+await cleanup. Use a descriptive `timeoutMsg`. Enable video with
+`IOCDService({ videoRecording: { ... } })` — videos are kept for failed specs and help diagnose
+failures that don't reproduce locally.

package/dist/templates/tests/tests/README.md

@@ -0,0 +1,79 @@
+# io.Connect Desktop seed tests
+
+End-to-end tests for the seed's **io.Connect Desktop** platform and the apps that run in it, built
+on [WebdriverIO 9](https://webdriver.io/) and `@interopio/wdio-iocd-service`. Specifications run in
+the WebdriverIO worker through the `platform-wdio` runner: the service starts a dedicated platform
+instance and lets a test start apps, call io.Connect APIs, switch the browser context into an app
+window, and drive its UI.
+
+## Running
+
+Run from the **seed root** (not this folder) so the CLI can resolve the platform executable and the
+license:
+
+```cmd
+# All specifications.
+npm test
+
+# One specification.
+npm test -- --spec ./tests/single-app.spec.ts
+```
+
+Type-check the specifications without starting the platform:
+
+```cmd
+cd tests
+npm run typecheck
+```
+
+## Layout
+
+- `wdio.config.ts` — WebdriverIO + `IOCDService` configuration (the `platform-wdio` runner).
+- `config/system.json` — platform overrides applied only to the test process.
+- `tests/common/iocd.ts` — polling, event-waiting, and cleanup-registry helpers.
+- `tests/config/apps.json` — fixture app definitions.
+- `tests/assets/applications/` — static fixture app HTML.
+- `tests/*.spec.ts` — the specifications below.
+
+## Sample specifications
+
+| Specification | What it demonstrates |
+| --- | --- |
+| `single-app.spec.ts` | Start one app, switch to its window, click a button, and assert its DOM. |
+| `channel-selector.spec.ts` | Select a Channel from the app's Web Group caption and verify that the client app observes its new membership. |
+| `shared-contexts.spec.ts` | Subscribe before a UI action, publish a Shared Context update from one app instance, verify the API event and receiving app DOM, and clean the subscription. |
+| `workspace-interop.spec.ts` | Restore a Workspace with two apps; select a person in one app and verify the other receives the Interop call. |
+| `interop.spec.ts` | Call an Interop method from the test itself: start an app that registers `IOCD.Sample.Add`, then `invoke` it and assert the result. |
+| `notifications.spec.ts` | Raise a notification, open the Notification Panel (`browser.switchToNotificationPanel()`), and assert it with `waitForChildrenCount()`. |
+| `workspace-add-app.spec.ts` | Add an app to a Workspace by clicking the frame's add button and the add-application popup with WebdriverIO, instead of the `addWindow()` API. |
+
+## Fixture apps
+
+`tests/config/apps.json` registers the fixture apps and points at `tests/assets/applications/`:
+
+- `web` — counter button (`single-app.spec.ts`).
+- `channel-client` — enables the caption Channel Selector and renders its current Channel
+  (`channel-selector.spec.ts`).
+- `shared-context-client` — publishes and subscribes to a named Shared Context
+  (`shared-contexts.spec.ts`).
+- `people-list` / `person-details` — Interop peers (`workspace-interop.spec.ts`).
+- `interop-responder` — registers the `IOCD.Sample.Add` Interop method (`interop.spec.ts`).
+- `workspace-widget` — marked `customProperties.includeInWorkspaces`, so it appears in the
+  add-application popup (`workspace-add-app.spec.ts`).
+
+## Built-in IOCD UI models
+
+Import page objects from `@interopio/wdio-iocd-service/models` when a test drives UI owned by IOCD,
+such as Web Groups, caption bars, tabs, and Channel Selectors. The generated service version exports
+the `Group`, `Frame`, caption/tab, button, Channel Selector, sizing-border, and approaching-marker
+models. `channel-selector.spec.ts` demonstrates the `Group` hierarchy.
+
+Available exports vary by service version. Check
+`node_modules/@interopio/wdio-iocd-service/dist/models/index.d.ts` before using a model; don't copy
+an import from a newer repository version without verifying that it exists in the generated test
+package. Use ordinary WebdriverIO selectors for UI owned by your app.
+
+## More
+
+- Full guide: the **Testing** section of the io.Connect Desktop seed-project documentation.
+- Coding-agent guidance: `.agents/skills/iocd-wdio-testing/` at the seed root.

package/dist/templates/tests/tests/config/system.json

@@ -0,0 +1,36 @@
+{
+  "advancedMode": false,
+  "channels": {
+    "enabled": true,
+    "definitions": [
+      { "name": "Red", "meta": { "color": "red" } },
+      { "name": "Green", "meta": { "color": "green" } }
+    ]
+  },
+  "appStores": [
+    {
+      "type": "path",
+      "details": {
+        "path": "%WDIO_TESTS_ROOT%/config/apps.json"
+      }
+    }
+  ],
+  "gw": {
+    "configuration": {
+      "port": 8385,
+      "ip": "127.0.0.1",
+      "authentication": {
+        "available": ["basic"],
+        "default": "basic"
+      }
+    }
+  },
+  "windowManagement": {
+    "group": {
+      "type": "Web"
+    }
+  },
+  "folders": {
+    "userData": "%WDIO_ROOT_DIR%/user-data"
+  }
+}