feat: add --test filter flag for targeted test runs by kevinccbsg · Pull Request #9 · BRIKEV/twd-cli

kevinccbsg · 2026-06-24T20:59:36Z

What

Adds a repeatable --test "<value>" flag to twd-cli run that runs only the tests whose full "Suite > test" path contains a filter value — for fast, targeted debugging from the CLI instead of always running the whole suite.

npx twd-cli run --test "shows error"
npx twd-cli run --test "Login"               # matches every test under describe("Login", …)
npx twd-cli run --test "Login" --test "Signup"  # OR'd

Behavior

Case-insensitive substring match against the full "Suite > test name" path, so passing a describe name runs all tests inside it — no separate flag needed.
Repeatable; multiple --test values are combined with OR.
Zero total matches → exits 1 with No tests matched filter(s): …, so a typo can't silently look like a pass. A partial match warns about the filters that matched nothing and proceeds.
Coverage collection is skipped while a filter is active (a filtered run is a partial/debug run).
No --test flag → unchanged behavior (full runAll()).

How

src/filterTests.js — selectTestIds(handlers, filters) matches in Node, reusing the existing buildTestPath helper.
src/parseArgs.js — parseRunArgs(argv) parses repeatable --test/--test= flags.
src/index.js — when filtering, enumerates the in-browser registry (window.__TWD_STATE__.handlers), selects ids in Node, and runs them via the existing window.__testRunner.runByIds(ids) (which still runs parent-suite beforeEach/afterEach hooks) instead of runAll().
bin/twd-cli.js — wires the flag in and documents it in --help.
README.md — new "Filtering tests" section.

No new dependencies.

Testing

New unit tests for selectTestIds and parseRunArgs.
New runTests tests: filtered run calls runByIds with the matched ids; zero-match returns exit 1 without running; coverage skipped under filter; partial-match warning.
Full suite green: 218 tests passing.

Design spec and implementation plan are committed under docs/superpowers/.

🤖 Generated with Claude Code

github-actions · 2026-06-24T21:00:02Z

TWD Contract Validation

Spec	Passed	Failed	Warnings	Mode
`./contracts/users-3.0.json`	2	3	1	`warn`
`./contracts/posts-3.1.json`	2	2	0	`warn`
`./contracts/products-3.0.json`	13	23	2	`warn`
`./contracts/events-3.1.json`	6	13	0	`warn`

23 passed · 41 failed · 3 warnings · 1 skipped

Failed validations

./contracts/users-3.0.json

GET /users/{userId} (200) — mock getUserNoAddress — in "Contract Validation - Mismatches > should fail: missing nested address field"
- response.address: missing required property "address"
GET /users/{userId} (200) — mock getUserBadAddress — in "Contract Validation - Mismatches > should fail: nested address missing required city"
- response.address.city: missing required property "city"
- response.address.country: missing required property "country"
GET /users/{userId} (200) — mock getUserBadRole — in "Contract Validation - Mismatches > should fail: oneOf role with invalid variant"
- response.role: oneOf best match (branch 2 of 2) failed: must be one of: "viewer"

./contracts/posts-3.1.json

GET /posts/{postId} (200) — mock getPostNoAuthor — in "Contract Validation - Mismatches > should fail: post missing nested author object"
- response.author: missing required property "author"
GET /posts/{postId} (200) — mock getPostBadMeta — in "Contract Validation - Mismatches > should fail: post oneOf metadata matches neither variant"
- response.metadata: oneOf best match (branch 1 of 2) failed: missing required property "category", unexpected property "duration", must be one of: "article"

./contracts/products-3.0.json

GET /products (200) — mock getProductEmptyName — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: empty name violates minLength"
- response[0].name: must NOT have fewer than 1 characters
GET /products (200) — mock getProductBadSku — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid SKU pattern"
- response[0].sku: must match pattern "^[A-Z]{2,4}-\d{4,8}$"
GET /products (200) — mock getProductBadUuid — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid uuid format for id"
- response[0].id: must match format "uuid"
GET /products (200) — mock getProductBadDateTime — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid date-time format"
- response[0].createdAt: must match format "date-time"
GET /products (200) — mock getProductBadDate — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid date format"
- response[0].releaseDate: must match format "date"
GET /products (200) — mock getProductBadEmail — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid email format"
- response[0].contactEmail: must match format "email"
GET /products (200) — mock getProductBadUri — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid uri format"
- response[0].website: must match format "uri"
GET /products (200) — mock getProductBadIp — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid ipv4 format"
- response[0].serverIp: must match format "ipv4"
GET /products (200) — mock getProductBadIpV6 — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid ipv6 format"
- response[0].serverIpV6: must match format "ipv6"
GET /products (200) — mock getProductZeroPrice — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: price of 0 violates exclusiveMinimum"
- response[0].price: must be > 0
GET /products (200) — mock getProductNegQty — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: negative quantity violates minimum"
- response[0].quantity: must be >= 0
GET /products (200) — mock getProductOverQty — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: quantity exceeds maximum"
- response[0].quantity: must be <= 999999
GET /products (200) — mock getProductBadWeight — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: weight not multipleOf 0.01"
- response[0].weight: must be multiple of 0.01
GET /products (200) — mock getProductBadRating — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: rating above maximum (5)"
- response[0].rating: must be <= 5
GET /products (200) — mock getProductBadCurrency — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid enum value for currency"
- response[0].currency: must be one of: "USD", "EUR", "GBP", "JPY"
GET /products (200) — mock getProductBadCategory — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid enum value for category"
- response[0].category: must be one of: "electronics", "clothing", "food", "books", "toys"
GET /products (200) — mock getProductBadBool — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: string value for boolean inStock"
- response[0].inStock: expected boolean, got string
GET /products (200) — mock getProductDupTags — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: duplicate tags violates uniqueItems"
- response[0].tags: must NOT have duplicate items (items ## 1 and 0 are identical)
GET /products (200) — mock getProductTooManyTags — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: tags exceeds maxItems (10)"
- response[0].tags: must NOT have more than 10 items
GET /products (200) — mock getProductBadMeta — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: non-string value in metadata additionalProperties"
- response[0].metadata.count: expected string, got number
GET /settings (200) — mock getSettingsBadExtra — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: extra property on Settings (additionalProperties: false)"
- response.extraField: unexpected property "extraField"
GET /settings (200) — mock getSettingsBadLang — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid language pattern in Settings"
- response.language: must match pattern "^[a-z]{2}(-[A-Z]{2})?$"
GET /products (200) — mock getProductBadNullable — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: wrong type for nullable description (number instead of string|null)"
- response[0].description: expected string,null, got number

./contracts/events-3.1.json

GET /events (200) — mock getEventsEmpty — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: empty events array violates minItems (1)"
- response: must NOT have fewer than 1 items
GET /events (200) — mock getEventShortName — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: event name too short (minLength: 3)"
- response[0].name: must NOT have fewer than 3 characters
GET /events (200) — mock getEventBadDate — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid date-time format for startDate"
- response[0].startDate: must match format "date-time"
GET /events (200) — mock getEventFloatId — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: float value for integer id"
- response[0].id: expected integer, got number
- response[0].id: must match format "int64"
GET /events (200) — mock getEventBadBool — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: number value for boolean active"
- response[0].active: expected boolean, got number
GET /events (200) — mock getEventBadStatus — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid enum value for status"
- response[0].status: must be one of: "draft", "published", "archived"
GET /events (200) — mock getEventScoreMax — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: score at exclusiveMaximum boundary (100)"
- response[0].score: must be < 100
GET /events (200) — mock getEventLowPriority — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: priority below minimum (1)"
- response[0].priority: must be >= 1
GET /events (200) — mock getEventHighPriority — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: priority above maximum (5)"
- response[0].priority: must be <= 5
GET /events (200) — mock getEventDupAttendees — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: duplicate attendees violates uniqueItems"
- response[0].attendees: must NOT have duplicate items (items ## 1 and 0 are identical)
GET /events (200) — mock getEventNoAttendees — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: empty attendees array violates minItems (1)"
- response[0].attendees: must NOT have fewer than 1 items
GET /events (200) — mock getEventBadAttendee — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid email format in attendees"
- response[0].attendees[0]: must match format "email"
GET /events/{eventId} (200) — mock getEventBadNullable — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: wrong type for nullable description (number instead of string|null)"
- response.description: expected string,null, got number

View full report →

github-actions · 2026-06-25T21:20:10Z

TWD Contract Validation

Spec	Passed	Failed	Warnings	Mode
`./contracts/users-3.0.json`	2	3	1	`warn`
`./contracts/posts-3.1.json`	2	2	0	`warn`
`./contracts/products-3.0.json`	13	23	2	`warn`
`./contracts/events-3.1.json`	6	13	0	`warn`

23 passed · 41 failed · 3 warnings · 1 skipped

Failed validations

./contracts/users-3.0.json

GET /users/{userId} (200) — mock getUserNoAddress — in "Contract Validation - Mismatches > should fail: missing nested address field"
- response.address: missing required property "address"
GET /users/{userId} (200) — mock getUserBadAddress — in "Contract Validation - Mismatches > should fail: nested address missing required city"
- response.address.city: missing required property "city"
- response.address.country: missing required property "country"
GET /users/{userId} (200) — mock getUserBadRole — in "Contract Validation - Mismatches > should fail: oneOf role with invalid variant"
- response.role: oneOf best match (branch 2 of 2) failed: must be one of: "viewer"

./contracts/posts-3.1.json

GET /posts/{postId} (200) — mock getPostNoAuthor — in "Contract Validation - Mismatches > should fail: post missing nested author object"
- response.author: missing required property "author"
GET /posts/{postId} (200) — mock getPostBadMeta — in "Contract Validation - Mismatches > should fail: post oneOf metadata matches neither variant"
- response.metadata: oneOf best match (branch 1 of 2) failed: missing required property "category", unexpected property "duration", must be one of: "article"

./contracts/products-3.0.json

GET /products (200) — mock getProductEmptyName — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: empty name violates minLength"
- response[0].name: must NOT have fewer than 1 characters
GET /products (200) — mock getProductBadSku — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid SKU pattern"
- response[0].sku: must match pattern "^[A-Z]{2,4}-\d{4,8}$"
GET /products (200) — mock getProductBadUuid — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid uuid format for id"
- response[0].id: must match format "uuid"
GET /products (200) — mock getProductBadDateTime — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid date-time format"
- response[0].createdAt: must match format "date-time"
GET /products (200) — mock getProductBadDate — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid date format"
- response[0].releaseDate: must match format "date"
GET /products (200) — mock getProductBadEmail — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid email format"
- response[0].contactEmail: must match format "email"
GET /products (200) — mock getProductBadUri — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid uri format"
- response[0].website: must match format "uri"
GET /products (200) — mock getProductBadIp — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid ipv4 format"
- response[0].serverIp: must match format "ipv4"
GET /products (200) — mock getProductBadIpV6 — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid ipv6 format"
- response[0].serverIpV6: must match format "ipv6"
GET /products (200) — mock getProductZeroPrice — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: price of 0 violates exclusiveMinimum"
- response[0].price: must be > 0
GET /products (200) — mock getProductNegQty — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: negative quantity violates minimum"
- response[0].quantity: must be >= 0
GET /products (200) — mock getProductOverQty — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: quantity exceeds maximum"
- response[0].quantity: must be <= 999999
GET /products (200) — mock getProductBadWeight — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: weight not multipleOf 0.01"
- response[0].weight: must be multiple of 0.01
GET /products (200) — mock getProductBadRating — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: rating above maximum (5)"
- response[0].rating: must be <= 5
GET /products (200) — mock getProductBadCurrency — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid enum value for currency"
- response[0].currency: must be one of: "USD", "EUR", "GBP", "JPY"
GET /products (200) — mock getProductBadCategory — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid enum value for category"
- response[0].category: must be one of: "electronics", "clothing", "food", "books", "toys"
GET /products (200) — mock getProductBadBool — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: string value for boolean inStock"
- response[0].inStock: expected boolean, got string
GET /products (200) — mock getProductDupTags — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: duplicate tags violates uniqueItems"
- response[0].tags: must NOT have duplicate items (items ## 1 and 0 are identical)
GET /products (200) — mock getProductTooManyTags — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: tags exceeds maxItems (10)"
- response[0].tags: must NOT have more than 10 items
GET /products (200) — mock getProductBadMeta — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: non-string value in metadata additionalProperties"
- response[0].metadata.count: expected string, got number
GET /settings (200) — mock getSettingsBadExtra — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: extra property on Settings (additionalProperties: false)"
- response.extraField: unexpected property "extraField"
GET /settings (200) — mock getSettingsBadLang — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: invalid language pattern in Settings"
- response.language: must match pattern "^[a-z]{2}(-[A-Z]{2})?$"
GET /products (200) — mock getProductBadNullable — in "Contract Validation - Products Mismatches (OpenAPI 3.0 — error mode) > should fail: wrong type for nullable description (number instead of string|null)"
- response[0].description: expected string,null, got number

./contracts/events-3.1.json

GET /events (200) — mock getEventsEmpty — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: empty events array violates minItems (1)"
- response: must NOT have fewer than 1 items
GET /events (200) — mock getEventShortName — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: event name too short (minLength: 3)"
- response[0].name: must NOT have fewer than 3 characters
GET /events (200) — mock getEventBadDate — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid date-time format for startDate"
- response[0].startDate: must match format "date-time"
GET /events (200) — mock getEventFloatId — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: float value for integer id"
- response[0].id: expected integer, got number
- response[0].id: must match format "int64"
GET /events (200) — mock getEventBadBool — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: number value for boolean active"
- response[0].active: expected boolean, got number
GET /events (200) — mock getEventBadStatus — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid enum value for status"
- response[0].status: must be one of: "draft", "published", "archived"
GET /events (200) — mock getEventScoreMax — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: score at exclusiveMaximum boundary (100)"
- response[0].score: must be < 100
GET /events (200) — mock getEventLowPriority — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: priority below minimum (1)"
- response[0].priority: must be >= 1
GET /events (200) — mock getEventHighPriority — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: priority above maximum (5)"
- response[0].priority: must be <= 5
GET /events (200) — mock getEventDupAttendees — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: duplicate attendees violates uniqueItems"
- response[0].attendees: must NOT have duplicate items (items ## 1 and 0 are identical)
GET /events (200) — mock getEventNoAttendees — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: empty attendees array violates minItems (1)"
- response[0].attendees: must NOT have fewer than 1 items
GET /events (200) — mock getEventBadAttendee — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: invalid email format in attendees"
- response[0].attendees[0]: must match format "email"
GET /events/{eventId} (200) — mock getEventBadNullable — in "Contract Validation - Events Mismatches (OpenAPI 3.1 — error mode) > should fail: wrong type for nullable description (number instead of string|null)"
- response.description: expected string,null, got number

View full report →

kevinccbsg added 8 commits June 23, 2026 10:43

docs: design spec for --test filter flag

56ee7c2

docs: implementation plan for --test filter flag

43794d6

feat: add selectTestIds matcher for test filtering

c4a1b46

feat: add parseRunArgs CLI argument parser

0c2d085

feat: filter tests via --test in runTests

bfc0943

feat: parse --test flag in CLI entry point

f5b1918

docs: document --test filter flag

12322c8

refactor: clarify partial-match filter warning and cover it with a test

966967b

chore: re-trigger PR checks

477e3d6

kevinccbsg merged commit 795e76e into main Jun 25, 2026
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add --test filter flag for targeted test runs#9

feat: add --test filter flag for targeted test runs#9
kevinccbsg merged 9 commits into
mainfrom
feat/filter-tests

kevinccbsg commented Jun 24, 2026

Uh oh!

github-actions Bot commented Jun 24, 2026

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

kevinccbsg commented Jun 24, 2026

What

Behavior

How

Testing

Uh oh!

github-actions Bot commented Jun 24, 2026

TWD Contract Validation

Uh oh!

github-actions Bot commented Jun 25, 2026

TWD Contract Validation

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant