@testiq/framework-core

PlayIQ — a Playwright + Cucumber automation engine with a Claude agent layer and a local agent console.

Projects built on it hold only what is specific to their application: features, step definitions, page objects, locators, and data. Everything else — browser lifecycle, logging, screenshots, waits, assertions, Excel test data, reporting, and the rules that keep generated code consistent — lives here.

Install

npm install @testiq/framework-core

Peer dependencies (@cucumber/cucumber, playwright, @playwright/test, docx, dotenv, exceljs, fs-extra) are installed in the consuming project.

Start a project

npx @testiq/framework-core init my-project
cd my-project
npm install
npx playwright install chromium

Or extract the starter kit zip and run setup.bat.

Launch the agent console

The console belongs to PlayIQ, not to the projects it operates on. Run it once and point it at any TestIQ project on this machine:

npx @testiq/framework-core ui --project "C:\path\to\project"

It serves a browser UI on localhost that drives your local Claude Code CLI in headless streaming mode. Everything stays on your machine: the CLI runs with the target project as its working directory, uses your existing Claude Code auth, and the browser is only a display surface talking to the local server.

Paste a DOM snippet or a URL, describe a flow, and it generates locators, page objects, features, and steps — then runs them and streams the result back.

What is in the package

| Path | Contents | |---|---| | index.js | All framework exports | | pages/BasePage.js | Base class for page objects | | utils/ | UI actions, waits, assertions, screenshots, logging, Excel, reports | | errors/ | FrameworkError and typed subclasses | | config/ | App, environment, and test configuration | | tests/support/ | Cucumber world and hooks | | runners/ | Test and report runners | | claude/ | Canonical agent rules, skills, and subagents | | starter-kit/ | Project skeleton scaffolded by init | | ui/ | The local agent console |

The Claude layer

claude/rules.md is the single source of truth for framework conventions. Scaffolded projects get a thin CLAUDE.md that imports it from node_modules, so updating this package updates the rules in every project.

claude/skills/ holds the task procedures and claude/agents/ the subagent personas. Projects get thin stubs in .claude/ that point back here.

Regenerate the stubs after editing claude/manifest.json:

npm run build:starter-claude
npm run build:starter          # also rebuilds dist/playiq-starter-kit-<version>.zip

Core conventions

feature file
  └─ step definition          (thin — no selectors, no waits, no asserts)
      └─ page object method    (business intent)
          └─ locator module    (selectors only)
              └─ core utils    (logging, screenshots, waits, assertions)

Page objects pass their locator module to super():

import { BasePage } from "@testiq/framework-core";
import LoginLocators from "../locators/LoginLocators.js";

export class LoginPage extends BasePage {
  constructor(page) {
    super(page, LoginLocators);
  }

  async loginWithCredentials(username, password) {
    await this.uiUtils.clearAndFillWithLog(
      this.locator("usernameInput"), username, "Username Input", this.ctx()
    );
    await this.uiUtils.clickWithLog(this.locator("loginButton"), "Login Button", this.ctx());
  }
}

Every *WithLog call logs the action, screenshots on failure, masks sensitive values, and feeds the report — automatically.

Configuring the application under test

AppConfig reads from the consuming project, in this order:

1. <project>/src/config/AppConfig.json
2. <project>/AppConfig.json
3. APP_NAME / BASE_URL environment variables
4. Built-in fallback

Developing this package locally

Consuming projects should link it with install-links=true in .npmrc so it is copied rather than symlinked. A symlink makes Node resolve the framework's peer dependencies from this package's own path instead of the project's, which surfaces as Cucumber's "two instances" error.

This package has no runtime dependencies of its own, so do not run npm install here — npm would install the peer dependencies locally and reintroduce exactly that duplicate-instance problem.

Because the copy is keyed on version, refresh a consumer after local edits with:

rm -rf node_modules/@testiq && npm install