QKForce Framework CWQ

Generated project execution

Frontend-generated suites use test/qkforce/manifest.json (schema 1), exact feature paths, steps.mjs and selectors.json. The runtime loads only that selection, supplies explicit Cucumber imports and drains legacy palette actions in order. Packaged workspaces without generated inputs fail instead of running template examples. Regenerate projects after migrating to this template revision; publish the runtime to the actual DB-configured Git remote before deploying API #108/frontend #61.

npm run test:contract covers config, immutable test data and generated-workspace validation. The separate HTML-report entrypoint gap remains #8. Real browser/client execution remains the release gate.

The QKForce browser-automation template is the fixed TypeScript + Cucumber + WebdriverIO + QKTestAnalytics profile.

Contract status

CWQ consumes the central v1.1 run config and optional package-local version-locked CSV inputs before WDIO starts. It does not create packages or receive results; those are API/Client responsibilities. The remaining documentation/operational concern is a verifiable required CI check, tracked in CWQ #6.

Run

npm ci
npm run qkforce:test
npm run qkforce:report

qkforce:test is the only execution entry point used by QKForce Client. Results belong under qreport-results/; raw test-data CSV files must not be copied into results archives.

Immutable run configuration

Every v1.1 workspace contains qkforce.config.json with numeric schemaVersion: 1, fixed profile id qkforce-wdio-cucumber-qkta, and run.targetUrl. The loader rejects unknown fields, non-fixed profiles, credentials/query/fragment URLs, non-HTTPS non-loopback targets, and target URLs over 2048 UTF-8 bytes.

{
  "schemaVersion": 1,
  "profile": {
    "id": "qkforce-wdio-cucumber-qkta",
    "language": "typescript",
    "bdd": "cucumber",
    "runner": "webdriverio",
    "adapter": "webdriverio-cucumber-node",
    "reporter": "qk-test-analytics"
  },
  "run": { "targetUrl": "https://example.test" }
}

Version-locked CSV test data

When test data is bound, QKForce materializes only immutable selected CSV versions below test-data/ and writes qkforce.test-data.lock.json. No lock is required for executions without bound test data. The framework preflights every present lock before WDIO starts and never fetches live data.

Validation covers schema version, unknown/duplicate metadata, safe package-local test-data/*.csv paths, regular-file/symlink checks, SHA-256, UTF-8, RFC-4180 quoting, unique headers and declared row count.

Use the typed step-definition helper:

import { Given } from '@wdio/cucumber-framework';
import { loadTestData } from '../support/test-data.js';

const testData = loadTestData();

Given('I use customer {string}', async (id: string) => {
  const customer = testData.dataset('customers').first({ id });
  await $('#username').setValue(customer.name);
});

Rows are immutable and scenario selection is never stored in global mutable state. Use row(index), where({...}) or first({...}) for deterministic addressing. typedRow(index, schema) supports string, integer, number, boolean (true/false) and ISO date (YYYY-MM-DD); { type, nullable: true } maps an empty cell to null.

Diagnostics identify dataset/version, row and column without printing cell contents. provenance() returns only testDataLockSha256 and {datasetId, versionId, sha256} entries, matching the QKForce results-manifest contract without raw CSV values.

Starter positive/negative fixtures live under test/fixtures/test-data/. Execution-specific CSV files are generated by QKForce and should not be hand-edited in the template.

Run non-browser validation with:

npm run check

Active development is performed on develop.

Fixed execution and reporting

npm run qkforce:test archives the previous cycle, runs WDIO, then builds qreport-results/index.html even when WDIO fails. The runner exit code is preserved; report failure makes a successful run fail. No command is accepted from the execution manifest. qkforce:report remains available for rebuilding an existing report. Cancellation or a forcibly terminated client cannot guarantee report generation.

4.3 KiB Raw Blame History