71 lines
3.1 KiB
Markdown
71 lines
3.1 KiB
Markdown
# QKForce Framework CWQ
|
|
|
|
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](https://github.com/QACGBDT/QKForce-Framework-CWQ/issues/6).
|
|
|
|
## Run
|
|
|
|
```bash
|
|
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.
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```bash
|
|
npm run check
|
|
```
|
|
|
|
Active development is performed on `develop`.
|