@esimplicitylabs/katalyst-xspec 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as playwright_bdd from 'playwright-bdd';
 export { test as baseTest } from 'playwright-bdd';
 import * as _playwright_test from '@playwright/test';
-import { APIResponse, PlaywrightTestArgs, PlaywrightWorkerArgs, APIRequestContext, Page } from '@playwright/test';
+import { APIResponse, APIRequestContext, PlaywrightTestArgs, PlaywrightWorkerArgs, Page } from '@playwright/test';
 export { isFlagEnabled, registerAllSteps, registerApiAssertionSteps, registerApiAuthSteps, registerApiHttpSteps, registerApiSteps, registerDebugSteps, registerFlagSteps, registerFormSteps, registerHybridSteps, registerHybridSuite, registerLayoutSteps, registerSharedCleanupSteps, registerSharedSteps, registerSharedVarSteps, registerTuiBasicSteps, registerTuiSteps, registerTuiWizardSteps, registerUiAuthSteps, registerUiBasicSteps, registerUiSteps, registerWizardSteps, setFlag } from './steps/index.js';
 
 type CleanupItem = {
@@ -685,11 +685,14 @@ declare function createOidcCleanupAuth(config?: OidcCleanupAuthConfig): CleanupA
 declare function resetOidcCleanupAuth(): void;
 
 type TagsForProjectInput = {
-    projectTag: string;
+    /** Optional tag a project is limited to, e.g. '@smoke'. Not needed for the built-in steps. */
+    projectTag?: string;
+    /** Extra tag expression, typically from `resolveExtraTags(process.env.TEST_TAGS)`. */
     extraTags?: string;
     defaultExcludes?: string;
 };
-declare function tagsForProject({ projectTag, extraTags, defaultExcludes }: TagsForProjectInput): string;
+/** Build a playwright-bdd `tags` expression: default excludes, optional project tag, optional extra tags. */
+declare function tagsForProject({ projectTag, extraTags, defaultExcludes }?: TagsForProjectInput): string;
 declare function resolveExtraTags(raw?: string | null): string | undefined;
 
 /**

package/dist/index.js

@@ -34,7 +34,7 @@ import {
   setupBypassAuth,
   setupFetchIntercept,
   tryParseJson
-} from "./chunk-ACAXOGKZ.js";
+} from "./chunk-UTTKW2SR.js";
 
 // src/fixtures.ts
 import { test as base } from "playwright-bdd";
@@ -972,9 +972,8 @@ function resetOidcCleanupAuth() {
 }
 
 // src/config.ts
-function tagsForProject({ projectTag, extraTags, defaultExcludes = "not @Skip and not @ignore" }) {
-  if (extraTags) return `${defaultExcludes} and ${projectTag} and (${extraTags})`;
-  return `${defaultExcludes} and ${projectTag}`;
+function tagsForProject({ projectTag, extraTags, defaultExcludes = "not @Skip and not @ignore" } = {}) {
+  return [defaultExcludes, projectTag, extraTags && `(${extraTags})`].filter(Boolean).join(" and ");
 }
 function resolveExtraTags(raw) {
   const tagFilterRaw = raw?.trim();

package/dist/steps/index.d.ts

@@ -36,7 +36,6 @@ declare function registerWizardSteps(test: any): void;
  * UI Form Step Definitions
  *
  * Steps for bulk form filling using Gherkin data tables.
- * Tagged with @ui or @hybrid for selective execution.
  */
 declare function registerFormSteps(test: any): void;
 
@@ -44,7 +43,6 @@ declare function registerFormSteps(test: any): void;
  * UI Debug Step Definitions
  *
  * Steps for debugging and troubleshooting UI tests.
- * Tagged with @ui or @hybrid for selective execution.
  */
 declare function registerDebugSteps(test: any): void;
 
@@ -52,7 +50,6 @@ declare function registerDebugSteps(test: any): void;
  * UI Layout Assertion Step Definitions
  *
  * Steps for asserting layout states like panels, split views, and responsive behavior.
- * Tagged with @ui or @hybrid for selective execution.
  */
 declare function registerLayoutSteps(test: any): void;
 
@@ -60,7 +57,6 @@ declare function registerLayoutSteps(test: any): void;
  * UI Auth Step Definitions
  *
  * Steps for authenticating in UI tests using fetch interception.
- * Tagged with @ui for selective execution.
  */
 declare function registerUiAuthSteps(test: any): void;
 
@@ -68,7 +64,6 @@ declare function registerUiAuthSteps(test: any): void;
  * TUI Basic Step Definitions
  *
  * Basic step definitions for terminal user interface testing.
- * Tagged with @tui for selective execution.
  * Aligned with ui.basic.ts patterns for consistency.
  */
 declare function registerTuiBasicSteps(test: any): void;
@@ -77,19 +72,16 @@ declare function registerTuiBasicSteps(test: any): void;
  * TUI Wizard Step Definitions
  *
  * Advanced step definitions for terminal user interface testing.
- * Tagged with @tui for selective execution.
  * Aligned with ui.wizard.ts patterns for consistency.
  */
 declare function registerTuiWizardSteps(test: any): void;
 
 /**
  * Register all API step definitions.
- * Steps are tagged with @api or @hybrid for selective execution.
  */
 declare function registerApiSteps(test: any): void;
 /**
  * Register all UI step definitions.
- * Steps are tagged with @ui or @hybrid for selective execution.
  *
  * Includes:
  * - Basic UI steps (navigation, clicks, fills)
@@ -116,7 +108,6 @@ declare function registerSharedSteps(test: any): void;
 declare function registerHybridSuite(test: any): void;
 /**
  * Register all TUI (Terminal User Interface) step definitions.
- * Steps are tagged with @tui for selective execution.
  *
  * @example
  * ```typescript

package/dist/steps/index.js

@@ -22,7 +22,7 @@ import {
   registerUiSteps,
   registerWizardSteps,
   setFlag
-} from "../chunk-ACAXOGKZ.js";
+} from "../chunk-UTTKW2SR.js";
 export {
   isFlagEnabled,
   registerAllSteps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esimplicitylabs/katalyst-xspec",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -58,7 +58,7 @@
   "peerDependencies": {
     "@playwright/test": "^1.49.0",
     "playwright-bdd": "^9.1.0",
-    "tui-tester": "^1.0.0",
+    "tui-tester": "^0.3.0",
     "typescript": "^5.6.0"
   },
   "peerDependenciesMeta": {

package/skills/katalyst-bdd-architecture/SKILL.md

@@ -164,7 +164,7 @@ const test = createBddTest({
 ```typescript
 createApi: (ctx) => {
   ctx.apiRequest;  // Playwright APIRequestContext
-  ctx.page;        // Playwright Page (for @ui)
+  ctx.page;        // Playwright Page
   // Return your ApiPort implementation
 }
 
@@ -192,14 +192,14 @@ When('I do something with {string}', async ({ world }, param: string) => {
   world.vars['result'] = param;
 });
 
-// Step with tag restriction
-When('I make API call', { tags: '@api or @hybrid' }, async ({ api, world }) => {
+// Step using the API fixture (no tags needed; works in any scenario)
+When('I make API call', async ({ api, world }) => {
   const result = await api.sendJson('GET', '/endpoint');
   world.lastJson = result.json;
 });
 
 // Step with multiple fixtures
-When('I verify in both layers', { tags: '@hybrid' }, async ({ api, ui, world }) => {
+When('I verify in both layers', async ({ api, ui, world }) => {
   await api.sendJson('POST', '/data', { value: 'test' });
   await ui.goto('/data');
   await ui.expectText('test');
@@ -481,13 +481,14 @@ selectPath(data, 'user.roles[0]');  // 'admin'
 ```typescript
 import { tagsForProject, resolveExtraTags } from '@esimplicitylabs/katalyst-xspec';
 
-// Build tag expression with defaults
-tagsForProject({ projectTag: '@api' });
-// Result: 'not @Skip and not @ignore and @api'
+// Build tag expression with defaults (projects select features by folder;
+// tags only skip @Skip/@ignore and apply optional TEST_TAGS)
+tagsForProject();
+// Result: 'not @Skip and not @ignore'
 
 // With extra tags
-tagsForProject({ projectTag: '@api', extraTags: '@smoke' });
-// Result: 'not @Skip and not @ignore and @api and (@smoke)'
+tagsForProject({ extraTags: resolveExtraTags(process.env.TEST_TAGS) });
+// e.g. TEST_TAGS=@smoke -> 'not @Skip and not @ignore and (@smoke)'
 ```
 
 ## File Organization

package/skills/katalyst-bdd-architecture/references/adapters.md

@@ -166,7 +166,7 @@ const test = createBddTest({
 ```bash
 # Admin credentials
 DEFAULT_ADMIN_USERNAME=admin@example.com
-DEFAULT_ADMIN_PASSWORD=admin123
+DEFAULT_ADMIN_PASSWORD=changeme
 
 # User credentials
 DEFAULT_USER_USERNAME=user@example.com

package/skills/katalyst-bdd-architecture/references/custom-steps.md

@@ -82,7 +82,7 @@ When I POST "/users" with JSON body:
 ```typescript
 import { DataTable } from '@cucumber/cucumber';
 
-When('I fill the form:', async ({ ui }, dataTable: DataTable) => {
+When('I fill the signup form:', async ({ ui }, dataTable: DataTable) => {
   const rows = dataTable.hashes();
   // rows = [{ Field: 'Email', Value: 'test@...' }, ...]
   
@@ -94,7 +94,7 @@ When('I fill the form:', async ({ ui }, dataTable: DataTable) => {
 
 **Usage:**
 ```gherkin
-When I fill the form:
+When I fill the signup form:
   | Field    | Value            |
   | Email    | test@example.com |
   | Password | secret123        |
@@ -120,30 +120,26 @@ const pairs = dataTable.rowsHash();
 // { Email: '...', Password: '...' }
 ```
 
-## Tag-Restricted Steps
+## Step Scope
+
+Custom steps don't need `{ tags: ... }`. Like the built-in steps, a step without tags works in any scenario, whichever fixtures it uses:
 
 ```typescript
-// Only available in @api scenarios
-When('I make an API call', { tags: '@api' }, async ({ api }) => {
+When('I make an API call', async ({ api }) => {
   // ...
 });
 
-// Available in @api or @hybrid
-When('I GET {string}', { tags: '@api or @hybrid' }, async ({ api, world }, path) => {
+When('I click something', async ({ ui }) => {
   // ...
 });
 
-// Only available in @ui
-When('I click something', { tags: '@ui' }, async ({ ui }) => {
+When('I create via API and check in UI', async ({ api, ui, world }) => {
   // ...
 });
-
-// Available everywhere (no tag restriction)
-Given('I set variable {string} to {string}', async ({ world }, name, value) => {
-  world.vars[name] = value;
-});
 ```
 
+Don't reuse wording of a built-in step (e.g. `I GET {string}`, `I set variable {string} to {string}`); a step text that matches two definitions is ambiguous.
+
 ## Available Fixtures
 
 Steps receive these fixtures:
@@ -285,7 +281,7 @@ import { expect } from '@playwright/test';
  * Custom steps for report generation testing
  */
 
-When('I generate a {string} report', { tags: '@api or @hybrid' }, 
+When('I generate a {string} report', 
   async ({ api, world }, reportType: string) => {
     const result = await api.sendJson('POST', '/reports/generate', {
       type: reportType,
@@ -301,7 +297,7 @@ When('I generate a {string} report', { tags: '@api or @hybrid' },
   }
 );
 
-When('I wait for the report to complete', { tags: '@api or @hybrid' },
+When('I wait for the report to complete',
   async ({ api, world }) => {
     const reportId = world.vars['reportId'];
     let attempts = 0;
@@ -323,7 +319,7 @@ When('I wait for the report to complete', { tags: '@api or @hybrid' },
   }
 );
 
-Then('the report should be downloadable', { tags: '@api or @hybrid' },
+Then('the report should be downloadable',
   async ({ api, world }) => {
     const reportUrl = world.vars['reportUrl'];
     expect(reportUrl).toBeDefined();
@@ -334,14 +330,14 @@ Then('the report should be downloadable', { tags: '@api or @hybrid' },
   }
 );
 
-When('I view the report in the UI', { tags: '@ui or @hybrid' },
+When('I view the report in the UI',
   async ({ ui, world }) => {
     const reportId = world.vars['reportId'];
     await ui.goto(`/reports/${reportId}`);
   }
 );
 
-Then('I should see the report preview', { tags: '@ui or @hybrid' },
+Then('I should see the report preview',
   async ({ ui }) => {
     await ui.expectText('Report Preview');
     await ui.expectElementState('first', 'pdf-viewer', 'locator', 'visible');

package/skills/katalyst-bdd-create-test/SKILL.md

@@ -1,39 +1,42 @@
 ---
 name: katalyst-bdd-create-test
-description: Create BDD tests for the Katalyst framework. Use when writing new feature files, creating test scenarios, choosing test types (@api, @ui, @tui, @hybrid), or implementing common testing patterns like CRUD operations, login flows, form handling, or API+UI verification workflows.
+description: Create BDD tests for the Katalyst framework. Use when writing new feature files, creating test scenarios, choosing where to put a test (features/api, features/ui, features/tui) or mixing API and UI steps, or implementing common testing patterns like CRUD operations, login flows, form handling, or API+UI verification workflows.
 ---
 
 # Katalyst BDD Test Creation Guide
 
 This skill guides you through creating BDD tests with the Katalyst framework.
 
-## Test Type Decision Tree
+## Where to Put a Test
 
-Choose the right tag based on what you're testing:
+Steps are untagged: any step works in any scenario. Do NOT add `@api`/`@ui`/`@hybrid`/`@tui` tags or `{ tags: ... }` on steps. Each Playwright project picks feature files by folder, so just choose the folder:
 
 ```
 What are you testing?
 │
-├─ HTTP API only → @api
+├─ HTTP API only → features/api/
 │  (REST endpoints, JSON responses, status codes)
 │
-├─ Browser UI only → @ui
+├─ Browser UI only → features/ui/
 │  (Pages, forms, buttons, navigation)
 │
-├─ Terminal UI only → @tui
+├─ Terminal UI only → features/tui/ (enable the tui project first)
 │  (CLI apps, interactive terminal programs)
 │
-└─ Multiple layers → @hybrid
+└─ API + UI in one scenario → features/ui/ (it needs a browser)
    (Create via API, verify in UI)
    (Setup data, then test UI flows)
 ```
 
+Tags are optional and only for the user's own grouping (`@smoke`, `@wip`, `@regression`).
+
 ## Feature File Structure
 
 Every feature file follows this structure:
 
 ```gherkin
-@tag
+# Tags are optional; this one is your own grouping
+@smoke
 Feature: Feature Name
   As a [role]
   I want [capability]
@@ -48,14 +51,13 @@ Feature: Feature Name
     Then [expected outcome]
 ```
 
-## Creating API Tests (`@api`)
+## Creating API Tests
 
 ### Step 1: Create Feature File
 
 Location: `features/api/[resource].feature`
 
 ```gherkin
-@api
 Feature: [Resource] API
   As a developer
   I want to test the [Resource] API
@@ -126,14 +128,13 @@ Scenario: Full [resource] lifecycle
 
 See [API Patterns](references/api-patterns.md) for more examples.
 
-## Creating UI Tests (`@ui`)
+## Creating UI Tests
 
 ### Step 1: Create Feature File
 
 Location: `features/ui/[page].feature`
 
 ```gherkin
-@ui
 Feature: [Page Name]
   As a user
   I want to [action on page]
@@ -176,14 +177,13 @@ Scenario: User login
 
 See [UI Patterns](references/ui-patterns.md) for more examples.
 
-## Creating TUI Tests (`@tui`)
+## Creating TUI Tests
 
 ### Step 1: Create Feature File
 
 Location: `features/tui/[command].feature`
 
 ```gherkin
-@tui
 Feature: [CLI Command]
   As a user
   I want to use the [command] CLI
@@ -192,7 +192,7 @@ Feature: [CLI Command]
 
 ### Step 2: Configure TUI in Fixtures
 
-Ensure your `fixtures.ts` has TUI configured:
+TUI is off in the scaffold. Uncomment `registerTuiSteps(test)` in `steps.ts`, the `tuiBdd` project in `playwright.config.ts`, and configure TUI in `fixtures.ts`:
 
 ```typescript
 createTui: () => new TuiTesterAdapter({
@@ -224,14 +224,15 @@ Scenario: Navigate menu
 
 See [TUI Patterns](references/tui-patterns.md) for more examples.
 
-## Creating Hybrid Tests (`@hybrid`)
+## Creating Hybrid Tests (API + UI)
+
+A hybrid test is just a scenario that mixes API and UI steps. No tag or special project is needed.
 
 ### Step 1: Create Feature File
 
-Location: `features/hybrid/[workflow].feature`
+Location: `features/ui/[workflow].feature` (or any folder a project reads)
 
 ```gherkin
-@hybrid
 Feature: [Workflow Name]
   As a tester
   I want to combine API and UI testing
@@ -336,21 +337,23 @@ And I store the value at "token" as "t"
 After creating feature files:
 
 ```bash
-# 1. Generate Playwright tests (REQUIRED)
-npm run gen
+# One-time: browser for UI tests
+npx playwright install chromium
 
-# 2. Run all tests
+# Generate specs and run all tests (npm test runs bddgen first)
 npm test
 
-# 3. Run specific project
-npx playwright test --project=api
-npx playwright test --project=ui
-npx playwright test --project=hybrid
+# Run one project (folder)
+npx playwright test --project api
+npx playwright test --project ui
+
+# Run only scenarios with your own tag
+TEST_TAGS=@smoke npm test
 
-# 4. Run specific feature
+# Run specific feature (after npm run gen)
 npx playwright test features/api/users.feature
 
-# 5. Debug mode
+# Debug mode
 npx playwright test --debug
 ```
 
@@ -358,8 +361,10 @@ npx playwright test --debug
 
 | Mistake | Solution |
 |---------|----------|
-| Forgot to run `npm run gen` | Always run after creating/modifying features |
-| Steps not available | Check you have the correct tag (`@api`, `@ui`, etc.) |
+| Forgot to run `npm run gen` | `npm test` does it; run it yourself before `npx playwright test` |
+| Adding `@api`/`@ui`/`@hybrid` tags | Not needed; steps work everywhere, projects select by folder |
+| Scenario never runs | Check the feature is in a folder a project reads |
+| Step not found | Check exact wording in `katalyst-bdd-step-reference` (TUI: `I fill the TUI form:`) |
 | Hardcoded test data | Use UUID generation for unique data |
 | No cleanup registered | Always register cleanup for created resources |
 | Scenarios depend on each other | Make each scenario independent |

package/skills/katalyst-bdd-create-test/references/api-patterns.md

@@ -7,7 +7,6 @@ Common patterns for API testing with the Katalyst BDD framework.
 ### List Resources
 
 ```gherkin
-@api
 Scenario: List all [resources]
   Given I am authenticated as an admin via API
   When I GET "/[endpoint]"
@@ -18,7 +17,6 @@ Scenario: List all [resources]
 ### Get Single Resource
 
 ```gherkin
-@api
 Scenario: Get [resource] by ID
   Given I am authenticated as an admin via API
   When I GET "/[endpoint]/1"
@@ -30,7 +28,6 @@ Scenario: Get [resource] by ID
 ### Create Resource
 
 ```gherkin
-@api
 Scenario: Create [resource]
   Given I am authenticated as an admin via API
   Given I generate a UUID and store as "runId"
@@ -50,7 +47,6 @@ Scenario: Create [resource]
 ### Update Resource (Full)
 
 ```gherkin
-@api
 Scenario: Update [resource] with PUT
   Given I am authenticated as an admin via API
   # First create the resource
@@ -75,7 +71,6 @@ Scenario: Update [resource] with PUT
 ### Update Resource (Partial)
 
 ```gherkin
-@api
 Scenario: Partial update with PATCH
   Given I am authenticated as an admin via API
   When I PATCH "/[endpoint]/{resourceId}" with JSON body:
@@ -89,7 +84,6 @@ Scenario: Partial update with PATCH
 ### Delete Resource
 
 ```gherkin
-@api
 Scenario: Delete [resource]
   Given I am authenticated as an admin via API
   # Create resource to delete
@@ -155,7 +149,6 @@ Scenario: Login and use token
 ### Not Found
 
 ```gherkin
-@api
 Scenario: Resource not found
   Given I am authenticated as an admin via API
   When I GET "/[endpoint]/99999"
@@ -165,7 +158,6 @@ Scenario: Resource not found
 ### Validation Error
 
 ```gherkin
-@api
 Scenario: Invalid data returns 400
   Given I am authenticated as an admin via API
   When I POST "/[endpoint]" with JSON body:
@@ -179,7 +171,6 @@ Scenario: Invalid data returns 400
 ### Unauthorized
 
 ```gherkin
-@api
 Scenario: Unauthorized access
   # No authentication
   When I GET "/admin/users"
@@ -189,7 +180,6 @@ Scenario: Unauthorized access
 ### Forbidden
 
 ```gherkin
-@api
 Scenario: User cannot access admin endpoint
   Given I am authenticated as a user via API
   When I GET "/admin/settings"
@@ -246,7 +236,6 @@ Then the value at "created_at" should match "^\d{4}-\d{2}-\d{2}"
 ### Pagination
 
 ```gherkin
-@api
 Scenario: Paginated list
   Given I am authenticated as an admin via API
   When I GET "/[endpoint]?page=1&limit=10"
@@ -260,7 +249,6 @@ Scenario: Paginated list
 ### Search/Filter
 
 ```gherkin
-@api
 Scenario: Filter by status
   Given I am authenticated as an admin via API
   When I GET "/[endpoint]?status=active"
@@ -271,7 +259,6 @@ Scenario: Filter by status
 ### Bulk Operations
 
 ```gherkin
-@api
 Scenario: Bulk create
   Given I am authenticated as an admin via API
   When I POST "/[endpoint]/bulk" with JSON body:
@@ -291,7 +278,6 @@ Scenario: Bulk create
 ### File Upload (Form Data)
 
 ```gherkin
-@api
 Scenario: Upload file
   Given I am authenticated as an admin via API
   Given I set header "Content-Type" to "multipart/form-data"
@@ -301,7 +287,6 @@ Scenario: Upload file
 ## Complete Example: User Management API
 
 ```gherkin
-@api
 Feature: User Management API
   As an admin
   I want to manage users via API