Quickstart

From sign-up to a verified, working install in ~15 minutes.

← Back to overview · 🇩🇪 Deutsch · Concepts →

Before you start

You need:

  • Node.js ≥ 20 (download)
  • A terminal (bash, zsh, PowerShell — all work)

💡 How does authentication work? The framework is distributed through a license-brokered npm proxy registry. Instead of an npm login or a GitHub-issued token, you authenticate with the License Key from your Welcome Email — no GitHub account is required for anything in this Quickstart.

Step 1 — Request access

Access to cc-testframework is granted after a brief vetting step. This lets us make sure the framework is the right fit for your team before we hand over repository access and a license key.

1a — Submit a demo request

  1. Go to cc-testframework.itsbusiness.ch and click Request a Demo.
  2. Fill in the demo-request form:
    • Full name
    • Work email
    • Company name
    • Use case (briefly describe what you intend to test)
  3. Submit the form.

You will see a confirmation: “We will get back to you within one business day.”

1b — Receive your personalized onboarding link

Once your request has been reviewed, you will receive an email from noreply@itsbusiness.ch containing a personalized sign-up link (/signup?token=...). This link is single-use and tied to your request.

1c — Complete the sign-up form

  1. Open the link from the email.
  2. Fill in the sign-up form:
    • Full name
    • Work email
    • Company name
  3. Submit the form.

Within a few minutes you will receive a Welcome Email from noreply@itsbusiness.ch containing:

  • A 14-day trial License Key (format: CC_LICENSE_KEY=<your-key>)
  • A link back to this Quickstart

If the Welcome Email doesn’t arrive within 10 minutes after completing the sign-up form, check your spam folder. If it’s not there either, contact support@itsbusiness.ch.

Step 2 — Locate your License Key

The only credential you need for install and every test run is the License Key from your Welcome Email (Step 1) — the same CC_LICENSE_KEY=<your-key> value that activates your trial.

  1. Open the Welcome Email from noreply@itsbusiness.ch.
  2. Copy the value after CC_LICENSE_KEY=.
  3. Keep it at hand — you’ll export it as an environment variable in Step 3, and again to persist it in Step 4.

⚠ Key hygiene Never commit the key into source code, never paste it into chat tools or screenshots, never share it via email. If you suspect a leak, contact support@itsbusiness.ch to have it rotated.

Step 3 — Bootstrap authentication and scaffold your project

The framework’s scaffolder — @meintest/cc-testframework-templates — is itself distributed through the same license-brokered proxy registry, so fetching it needs the same CC_LICENSE_KEY authentication as any other @meintest/... package. This is a one-time, one-off bootstrap, though: it deliberately does not create a persistent .npmrc at your repo’s outer root. The only persistent .npmrc this workflow ever creates lives inside pm/ — scaffolded a moment later by the same command. Pass the registry and key as one-off flags to npx instead of writing a file:

Linux / macOS (bash/zsh):

export CC_LICENSE_KEY=your-key-from-welcome-email

npx --@meintest:registry=https://itsbusiness.vercel.app/api/tmgmt/npm/ \
    --//itsbusiness.vercel.app/api/tmgmt/npm/:_authToken=$CC_LICENSE_KEY \
    @meintest/cc-testframework-templates init

Windows (PowerShell):

$env:CC_LICENSE_KEY="your-key-from-welcome-email"

npx --@meintest:registry=https://itsbusiness.vercel.app/api/tmgmt/npm/ `
    --//itsbusiness.vercel.app/api/tmgmt/npm/:_authToken=$env:CC_LICENSE_KEY `
    @meintest/cc-testframework-templates init

💡 Why not npm install --save-dev first? Installing the scaffolder as a project dependency would add — or create — a package.json at your repo’s outer root, exactly what this workflow avoids. npx fetches and runs it without installing anything persistent outside pm/.

This scaffolds a self-contained pm/ project at your current directory. Your repo’s outer root gets nothing:

pm/
├── package.json              ← @meintest/cc-testframework, @playwright/test, app dependencies
├── tsconfig.json
├── playwright.config.ts
├── .npmrc                    ← scaffolded from .npmrc.example, same two registry lines as above
├── 2_Apps/_Skeleton/          ← starter Controls + TestSteps
├── 3_Cases/TC_Example.spec.ts
└── … the remaining 9 numbered folders (.gitkeep-ed from minute zero)

See Concepts — The full project layout for what each of the 11 numbered folders — and the config files listed alongside them — is for.

After scaffolding:

  1. Rename pm/2_Apps/_Skeleton/ → pm/2_Apps/<YourApp>/ (e.g., pm/2_Apps/MyApp/).
  2. Adjust pm/tsconfig.json’s path aliases to your app folder name (replace <AppName> placeholders).
  3. Set baseURL in pm/playwright.config.ts to your application URL.

💡 A faster way to do step 1. npx cc-testframework create-web-app --name <YourApp> --url <your-app-url> (run from inside pm/) copies _Skeleton into a numbered 2_Apps/<N>_<YourApp>/ folder, substitutes the App-name placeholder, registers the entry in GlobalConfig.ts, and wires the global References.ts barrel for you — one command instead of a manual rename-and-edit. See Add a New App — Scaffold a Web app automatically with the CLI for flags and the resulting layout. Steps 2 and 3 above are unaffected either way.

💡 Upgrading an existing project? v0.25.0 moved package.json, tsconfig.json, playwright.config.ts, and .npmrc from your repo’s outer root into pm/ itself — see Concepts — Migrating to v0.25.0 for the before/after table.

Step 4 — Set the License Key

The License Key from your Welcome Email must be available as an environment variable — the same CC_LICENSE_KEY you exported for the one-off bootstrap in Step 3 also authenticates npm install (Step 5) and every test run.

💡 No .env file. The framework never auto-loads a .env file — CC_LICENSE_KEY needs to be a real environment variable in your terminal/operating system (same as the credentials described in Credential Management, the License Key is never written to a file in your project either).

For the current session

This is the same command as Step 3 — if you’ve stayed in the same terminal since then, you’ve already done this and can skip ahead to Step 5.

Linux / macOS (bash/zsh):

export CC_LICENSE_KEY=your-key-from-welcome-email

Windows (PowerShell):

$env:CC_LICENSE_KEY="your-key-from-welcome-email"

⚠ Current terminal only. This assignment lives exclusively in the open terminal session — a new terminal window, a reboot, or a new SSH session won’t know about it. For anything beyond the current session, see below.

Persist permanently

For CC_LICENSE_KEY to be available in future, freshly opened terminals, add it once to your operating system’s or shell’s persistent environment configuration.

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("CC_LICENSE_KEY", "your-key-from-welcome-email", "User")

Equivalent one-liner: setx CC_LICENSE_KEY "your-key-from-welcome-email". Both write to the persistent per-user environment variables — the currently open terminal does not pick up the change automatically, you need a new terminal window for that.

macOS (zsh — the default shell since macOS Catalina):

echo 'export CC_LICENSE_KEY=your-key-from-welcome-email' >> ~/.zshrc
source ~/.zshrc

source ~/.zshrc reloads the profile in the current terminal immediately; a freshly opened terminal window works just as well.

Linux (bash):

echo 'export CC_LICENSE_KEY=your-key-from-welcome-email' >> ~/.bashrc
source ~/.bashrc

💡 Which file is the right one for me? Unlike on Windows, there’s no single command that works on every Linux/macOS system — which file your shell reads at startup depends on distribution, login-shell type, and individual configuration (~/.bashrc, ~/.bash_profile, ~/.profile, ~/.zshrc, …). Check echo $SHELL to see which shell is active, and add the line to the matching profile file. If your terminal doesn’t start as a login shell, ~/.profile may be needed instead of ~/.bashrc.

Replace your-key-from-welcome-email in each command with the actual key from the Welcome Email. The key is case-sensitive.

💡 What if I skip this? If CC_LICENSE_KEY is not set, npm install in Step 5 fails with 401 Unauthorized (pm/.npmrc can’t resolve the token), and — once installed — tests still run but print a warning in the log: [cc-testframework license] No license key set. Provide CC_LICENSE_KEY=<your-key> in your environment. The session variant above is enough for Step 5; for every future test run in a new terminal you’ll need the persistent variant.

Step 5 — Install dependencies inside pm/ 

cd pm
npm install

pm/.npmrc (scaffolded in Step 3) references the same CC_LICENSE_KEY environment variable you set in Step 4 (or exported for the one-off bootstrap in Step 3, if you’re still in the same terminal session) — this just works. In a new terminal, re-export it first (same value as Step 4).

You should see something like:

added 96 packages, and audited 97 packages in 5s
found 0 vulnerabilities

This installs @meintest/cc-testframework, @playwright/test, and the runtime dependencies the shipped Apps need into pm/node_modules/.

If you get 401 Unauthorized, your CC_LICENSE_KEY is missing, invalid, or the env-var isn’t being picked up — see FAQ: 401 Unauthorized.

If you get 404 Not Found, the proxy registry didn’t recognize the package name or your license isn’t active yet. Double-check the package name is exactly @meintest/cc-testframework; if it is and you still get 404, contact support@itsbusiness.ch.

Step 6 — Verify your install

Run the starter test that came with the scaffold in Step 3 — no test code to write yet. From inside pm/ (or cd pm first if you’re in a fresh terminal):

npx playwright test 3_Cases/TC_Example.spec.ts

If everything is wired correctly, Playwright launches the browser (or runs headless, depending on your playwright.config.ts), executes the steps, and reports pass/fail.

At the start of the test run, look for a log line confirming your license is active:

[cc-testframework license] License valid until YYYY-MM-DD

This confirms the framework has read your CC_LICENSE_KEY and verified it. If you see a warning instead of this line, see the License troubleshooting section below.

💡 What’s inside TC_Example.spec.ts? A short flow composed with Project.Core.test(...) and Project.Core.Step.numberedStepBlock(...), calling TestSteps from the scaffolded _Skeleton App via the @GlobalRef barrel. This is the same pattern you write against your own application, starting in Add a New App.

A passing run confirms your environment is wired end-to-end — license key, templates, and Playwright itself. Building Controls, TestSteps, and TestCases against your own application starts in Add a New App.

After 14 days — what happens?

Approximately 2 days before your trial expires, you will receive a reminder email from noreply@itsbusiness.ch.

When the trial period ends:

  • Tests continue to run — the framework does not block execution.
  • The license log line changes to a warning: [cc-testframework license] License expired. Contact sales@itsbusiness.ch for renewal.

To convert to a paid license, contact sales@itsbusiness.ch. Your License Key stays the same — no changes to your project setup are needed. The next test run after renewal will pick up the new expiry automatically.

License troubleshooting

Log output Cause Fix
License valid until YYYY-MM-DD License active —
No license key set. Provide CC_LICENSE_KEY=<your-key> in your environment. CC_LICENSE_KEY env-var not set or not picked up Re-run the export from Step 4, verify with echo $CC_LICENSE_KEY
License key not recognized. Key invalid or mistyped Copy the key again from the Welcome Email exactly as sent; contact support@itsbusiness.ch if it persists
License expired. Contact sales@itsbusiness.ch for renewal. Trial ended Contact sales@itsbusiness.ch

💡 Network issues The framework caches the license check for 7 days. If your network blocks outbound requests to the license server, the last cached result is used. Tests will not fail due to transient network issues.

What’s next?

  • Concepts — understand the three-layer architecture before building out your app-layer
  • Add a New App — register your Application-Under-Test and pick a platform tool
  • API Reference — the curated set of framework primitives (Action, Check, Step, baseConfig, …)
  • FAQ — troubleshooting for the most common setup hiccups

📧 Technical issues: support@itsbusiness.ch · Licensing & billing: sales@itsbusiness.ch

itsbusiness AG · Bern · Switzerland