Scaffold a New App

The fastest way to add a new Application-Under-Test: one CLI command, done.

← Back to overview · 🇩🇪 Deutsch · ← Concepts · Add a New App (full guide) →

Web app

npx cc-testframework create-web-app --name MyApp --url https://myapp.example

Scaffolds the app under 2_Apps/ and registers it — done, Project.MyApp.* is ready to use in a TestCase. Add --dry-run to preview what would be created without writing anything.

Desktop app (Appium-Windows)

npx cc-testframework create-desktop-app --name MyApp --executable "C:\apps\MyApp.exe"

Scaffolds the app under 2_Apps/ and registers it — done, Project.MyApp.* is ready to use in a TestCase. Add --dry-run to preview what would be created without writing anything.

Electron app

npx cc-testframework create-electron-app --name MyApp --executable-path "/opt/MyApp/MyApp"

Scaffolds the app (Web Controls + Electron launch) and registers it — done. It’s a Playwright/Web-family launch (an Electron renderer is a Chromium DOM), so it reuses the Web Controls — the only difference from a Web app is it launches an executable instead of a URL (type: 'Web', tool: 'Playwright', executablePath). Add --dry-run to preview what would be created without writing anything.

Then write a test

npx cc-testframework create-testcase --name MyTest --app MyApp

Scaffolds 3_Cases/TC_MyTest.spec.ts with a Setup block that starts MyApp — run it with npx playwright test 3_Cases/TC_MyTest.spec.ts. Omit --name to be prompted for it interactively; omit --app for a bare TODO skeleton instead of the Setup block.

You do not hand-write locators first. With Self-Healing enabled (SELF_HEALING_WRITEBACK=true + an AI API key — AI_API_KEY, npx cc-testframework set-ai-key, or the legacy ANTHROPIC_API_KEY, see Self-Healing Locators — Cost and BYOK), the framework discovers your app’s real locators automatically the first time the scaffolded, generic Controls miss — no hand-editing of Controls/Steps needed before your first run. Without Self-Healing enabled, nothing heals — see Self-Healing Locators to turn it on.

Add a shipped default app

npx cc-testframework add-app ftp-client     # pull in the FtpClient app
npx cc-testframework add-app --list         # show the catalog

Instead of scaffolding a blank app, add-app pulls in a complete, ready-to-use app the framework ships — email, ftp-client, os-common, os-windows, utilities — no naming, no locators to write. Each one needs its own setup before it works (credentials, OAuth, an Appium-Windows host, …); the command tells you exactly what, and --list shows every app’s description and setup hint upfront. These are context-free tool apps — wired into References.ts as Project.FtpClient.* etc., no GlobalConfig.apps entry needed.

Keep an app in sync with templates

When the shipped _Skeleton* templates improve, apps you already scaffolded from them don’t pick that up automatically. Re-sync one with:

npx cc-testframework-update-app --app MyApp

This runs as a dry-run by default — nothing is written. It prints a status table for every file under the app’s 1_Controls//2_Steps/: up-to-date, update (template changed, you didn’t — safe), skip (you edited it, template didn’t change), conflict (both changed — needs a decision), new (template added a file you don’t have yet), or template-removed. Add --json for a machine-readable report.

npx cc-testframework-update-app --app MyApp --apply    # writes only the safe `update`/`new` files
npx cc-testframework-update-app --app MyApp --force    # also resolves conflicts: backs up your file to <file>.bak, then writes the template version

A Control or Step you edited by hand — or one a Self-Healing writeback already patched — is never silently overwritten; a conflict needs --force before anything changes, and even then your prior content is preserved as <file>.bak right next to it.

💡 .cc-scaffold.json. init and add-app write this baseline marker at your pm/ root — the pristine hash of every file they scaffold. It’s what lets update-app tell “the template changed this” apart from “you changed this.” Commit it to version control. Apps scaffolded before this marker existed still work — update-app falls back to a more conservative comparison for them (any difference from the current template counts as a conflict, so it’s never guessed away).

Checking compatibility before you update

Every published version of @meintest/cc-testframework-templates ships a manifest.json — the same file init/create-*/update-app already read to scaffold and sync your apps. Next to its existing compatibility pin (the matching @meintest/cc-testframework version range), that manifest carries a machine-readable supportMatrix block: the external component versions that release of the framework is tested and supported against.

"supportMatrix": {
  "schemaVersion": 1,
  "playwright": ">=1.49.0 <2.0.0",
  "node": ">=20",
  "appium": ">=2.0.0",
  "browser": { "chromium": ">=131.0.0" },
  "outlook": "Microsoft 365 (Graph API)"
}

💡 The ranges above are an example from one released version. They shift release to release, as the framework’s own Playwright/Node floor moves and as Appium/browser support is re-verified — never treat a copy pasted from these docs as current. Always read the supportMatrix of the specific version you’re about to install.

Field	Meaning
`schemaVersion`	The stable contract for anything parsing this block. Only bumped if the block’s shape itself changes — safe to key tooling off this instead of the framework version.
`playwright`	The `@playwright/test` version range this framework release is built and tested against.
`node`	The minimum Node.js version this framework release requires.
`appium`	The minimum Appium server major version for Desktop/Mobile tests. The Appium server itself runs outside this npm package (see Add a New App for Appium setup) — this is a support statement, not a dependency your package manager installs.
`browser.chromium`	The Chromium major version bundled by the supported Playwright floor — relevant if your environment pins a specific browser build.
Any other component (e.g. `outlook`)	Appears only when a shipped App actually supports it — see Add a shipped default app above. A component’s absence means no shipped App currently covers it, not that it’s permanently unsupported.

Compare supportMatrix against your own environment — Node version, the Playwright version pinned in pm/package.json, your Appium server version, your browser build — before installing a newer framework release, to see whether it still fits without installing it first. The same block is what any external tooling consuming this package (a CI check, an internal compatibility script, a test-management tool) can parse, instead of scraping release notes.

To inspect it without installing anything into your project, download just the package tarball with the same registry authentication as Quickstart — Step 3 and read the file straight out of it:

npm pack @meintest/cc-testframework-templates@<target-version> \
    --registry=https://itsbusiness.vercel.app/api/tmgmt/npm/ \
    --//itsbusiness.vercel.app/api/tmgmt/npm/:_authToken=$CC_LICENSE_KEY

tar -xzf meintest-cc-testframework-templates-<target-version>.tgz package/manifest.json -O

Replace <target-version> with the version you’re considering, or drop @<target-version> for the latest.

Need more control?

Manual GlobalConfig registration, more on Electron (lifecycle steps, prerequisites), Mobile apps, or wiring in an app whose Controls you already hand-built — all covered in the full guide.

📧 Questions? Contact: jens.szelag@itsbusiness.ch

itsbusiness AG · Bern · Switzerland