@esimplicitylabs/katalyst-xspec 0.6.0

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

@@ -0,0 +1,415 @@
+# UI Test Patterns
+
+Common patterns for UI testing with the Katalyst BDD framework.
+
+## Navigation Patterns
+
+### Basic Navigation
+
+```gherkin
+@ui
+Scenario: Navigate to page
+  Given I navigate to "/dashboard"
+  Then I should see text "Dashboard"
+  And the URL should contain "/dashboard"
+```
+
+### Navigation with Auth
+
+```gherkin
+@ui
+Scenario: Navigate after login
+  Given I am authenticated in UI as "user"
+  Given I navigate to "/profile"
+  Then I should see text "My Profile"
+```
+
+### Back Navigation
+
+```gherkin
+@ui
+Scenario: Go back to previous page
+  Given I navigate to "/page1"
+  When I click the link "Go to Page 2"
+  Then the URL should contain "/page2"
+  When I go back in the browser
+  Then the URL should contain "/page1"
+```
+
+## Login Patterns
+
+### Simple Login Form
+
+```gherkin
+@ui
+Scenario: User login
+  Given I navigate to "/login"
+  When I fill in "Email" with "user@example.com"
+  And I fill in "Password" with "password123"
+  And I click the button "Sign In"
+  Then I should see text "Welcome"
+  And the URL should contain "/dashboard"
+```
+
+### Login with Fetch Intercept (Bypassing Auth)
+
+```gherkin
+@ui
+Scenario: Test page as authenticated user
+  Given I am authenticated in UI as "admin"
+  Given I navigate to "/admin/dashboard"
+  Then I should see text "Admin Dashboard"
+```
+
+### Login with Specific Roles
+
+```gherkin
+@ui
+Scenario: Test with multiple roles
+  Given I am authenticated in UI as "admin,manager,editor"
+  Given I navigate to "/settings"
+  Then I should see text "Admin Settings"
+  And I should see text "Manager Settings"
+```
+
+### Login with Tenant
+
+```gherkin
+@ui
+Scenario: Multi-tenant login
+  Given I am authenticated in UI as "admin" for tenant "acme-corp"
+  Given I navigate to "/dashboard"
+  Then I should see text "ACME Corp Dashboard"
+```
+
+## Form Patterns
+
+### Simple Form Fill
+
+```gherkin
+@ui
+Scenario: Fill contact form
+  Given I navigate to "/contact"
+  When I fill in "Name" with "John Doe"
+  And I fill in "Email" with "john@example.com"
+  And I fill in "Message" with "Hello, this is a test message."
+  And I click the button "Send"
+  Then I should see text "Message sent"
+```
+
+### Form with Data Table
+
+```gherkin
+@ui
+Scenario: Fill registration form
+  Given I navigate to "/register"
+  When I fill the form:
+    | Field          | Value                |
+    | First Name     | John                 |
+    | Last Name      | Doe                  |
+    | Email          | john.doe@example.com |
+    | Password       | SecurePass123!       |
+    | Confirm Password | SecurePass123!     |
+  And I click the button "Register"
+  Then I should see text "Account created"
+```
+
+### Form with Dropdowns
+
+```gherkin
+@ui
+Scenario: Fill form with dropdown
+  Given I navigate to "/settings"
+  When I fill in "Display Name" with "John"
+  And I select "Dark" from dropdown "Theme"
+  And I select "English" from dropdown "Language"
+  And I click the button "Save"
+  Then I should see text "Settings saved"
+```
+
+### Clear and Fill Form
+
+```gherkin
+@ui
+Scenario: Update existing form data
+  Given I navigate to "/profile/edit"
+  When I clear and fill the form:
+    | Field    | Value           |
+    | Name     | Updated Name    |
+    | Bio      | Updated bio     |
+  And I click the button "Save"
+  Then I should see text "Profile updated"
+```
+
+### Form Validation
+
+```gherkin
+@ui
+Scenario: Form shows validation errors
+  Given I navigate to "/register"
+  When I fill in "Email" with "invalid-email"
+  And I click the button "Register"
+  Then I should see text "Invalid email format"
+  And the element ".error-message" should be visible
+```
+
+## Click Patterns
+
+### Click Button
+
+```gherkin
+When I click the button "Submit"
+When I click the "Save" button
+```
+
+### Click Link
+
+```gherkin
+When I click the link "Learn More"
+When I click the link "Terms of Service"
+```
+
+### Click Element by Selector
+
+```gherkin
+When I click the element "#submit-btn"
+When I click the element ".menu-item.active"
+```
+
+### Click Element with Text
+
+```gherkin
+When I "click" the "button" element that contains "Save Changes"
+When I "force click" the "first" element with "test ID" "action-btn"
+```
+
+### Conditional Click
+
+```gherkin
+When If its visible, I "click" the "first" element with "text" "Dismiss"
+When If its visible, I "click" the "first" element with "role" "button"
+```
+
+## Assertion Patterns
+
+### Text Assertions
+
+```gherkin
+Then I should see text "Welcome"
+Then I should see text "User {userName}"
+Then I should not see text "Error"
+```
+
+### URL Assertions
+
+```gherkin
+Then the URL should contain "/dashboard"
+Then I should be on page "/users"
+Then I verify if the URL "equals" "https://example.com/home"
+Then I verify if the URL "doesntContain" "error"
+```
+
+### Element Visibility
+
+```gherkin
+Then the element "#modal" should be visible
+Then the element ".error" should not be visible
+Then I verify that a "button" element with "Submit" text "is" visible
+```
+
+### Element State
+
+```gherkin
+Then I verify that "first" element with "test ID" "submit" is "enabled"
+Then I verify that "first" element with "label" "Email" is "editable"
+Then the element "#terms" should be checked
+Then the element "#newsletter" should not be checked
+```
+
+### Element Value
+
+```gherkin
+Then the element "#email" should have value "test@example.com"
+Then the element "#quantity" should have value "5"
+```
+
+### Wait for State Change
+
+```gherkin
+Then I verify that "first" element with "text" "Loading" becomes "hidden" during "5" seconds
+Then I verify that "first" element with "test ID" "result" becomes "visible" during "3" seconds
+```
+
+## Modal/Dialog Patterns
+
+### Modal Interaction
+
+```gherkin
+@ui
+Scenario: Confirm deletion in modal
+  Given I navigate to "/items"
+  When I click the button "Delete"
+  Then I should see a modal dialog
+  And I should see text "Are you sure?"
+  When I click the button "Confirm"
+  Then I should not see a modal dialog
+  And I should see text "Item deleted"
+```
+
+### Cancel Modal
+
+```gherkin
+@ui
+Scenario: Cancel modal
+  Given I navigate to "/items"
+  When I click the button "Delete"
+  Then I should see a modal dialog
+  When I click the button "Cancel"
+  Then I should not see a modal dialog
+```
+
+## Tab/Navigation Patterns
+
+### Tab Interaction
+
+```gherkin
+@ui
+Scenario: Switch between tabs
+  Given I navigate to "/settings"
+  Then the "General" tab should be active
+  When I click the "Security" tab
+  Then the "Security" tab should be active
+  And I should see text "Password Settings"
+```
+
+### Sidebar Navigation
+
+```gherkin
+@ui
+Scenario: Sidebar navigation
+  Given I navigate to "/app"
+  Then the sidebar should be visible
+  When I click the link "Reports"
+  Then the URL should contain "/reports"
+```
+
+## Responsive Testing
+
+### Test Mobile View
+
+```gherkin
+@ui
+Scenario: Mobile navigation
+  Given the viewport is "mobile" size
+  Given I navigate to "/home"
+  Then the sidebar should be hidden
+  When I click the button "Menu"
+  Then the sidebar should be visible
+```
+
+### Test Custom Viewport
+
+```gherkin
+@ui
+Scenario: Test at specific resolution
+  Given the viewport is 1920x1080
+  Given I navigate to "/dashboard"
+  Then I should see a split view layout
+```
+
+## Wait Patterns
+
+### Fixed Wait
+
+```gherkin
+When I click the button "Submit"
+Then I wait "2" seconds
+Then I should see text "Success"
+```
+
+### Wait for Page Load
+
+```gherkin
+When I click the link "Heavy Page"
+Then I wait for the page to load
+Then I should see text "Content Loaded"
+```
+
+## Debug Patterns
+
+### Pause for Manual Inspection
+
+```gherkin
+When I pause for debugging
+```
+
+### Take Screenshot
+
+```gherkin
+When I save a screenshot as "login-page"
+When I save a full page screenshot as "dashboard-full"
+```
+
+### Log Information
+
+```gherkin
+Then I log the current URL
+Then I log the page title
+Then I print visible text
+Then I log all cookies
+```
+
+## Complete Example: E-commerce Checkout
+
+```gherkin
+@ui
+Feature: Checkout Flow
+  As a customer
+  I want to complete checkout
+  So that I can purchase products
+
+  Background:
+    Given I am authenticated in UI as "customer"
+
+  Scenario: Complete checkout process
+    # Add item to cart
+    Given I navigate to "/products/widget-123"
+    When I select "2" from dropdown "Quantity"
+    And I click the button "Add to Cart"
+    Then I should see text "Added to cart"
+    
+    # Go to cart
+    When I click the link "Cart"
+    Then I should see text "Shopping Cart"
+    And I should see text "Widget"
+    And I should see text "Qty: 2"
+    
+    # Proceed to checkout
+    When I click the button "Checkout"
+    Then I should see text "Shipping Information"
+    
+    # Fill shipping info
+    When I fill the form:
+      | Field    | Value           |
+      | Address  | 123 Main St     |
+      | City     | Springfield     |
+      | Zip      | 12345           |
+    And I click the button "Continue"
+    Then I should see text "Payment Information"
+    
+    # Fill payment info
+    When I fill in "Card Number" with "4111111111111111"
+    And I fill in "Expiry" with "12/25"
+    And I fill in "CVV" with "123"
+    And I click the button "Place Order"
+    
+    # Confirm order
+    Then I should see text "Order Confirmed"
+    And the URL should contain "/order-confirmation"
+
+  Scenario: Apply discount code
+    Given I navigate to "/cart"
+    When I fill in "Discount Code" with "SAVE20"
+    And I click the button "Apply"
+    Then I should see text "20% discount applied"
+```

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

@@ -0,0 +1,292 @@
+---
+name: katalyst-bdd-quickstart
+description: Get started with the Katalyst BDD testing framework. Use when setting up a new test project, scaffolding tests, configuring environment variables, understanding project structure, or running tests for the first time. Triggers on "set up tests", "install katalyst-xspec", "create test project", "configure BDD", "how to run tests".
+---
+
+# Katalyst BDD Quick Start Guide
+
+This skill helps you get started with the @esimplicitylabs/katalyst-xspec BDD testing framework.
+
+## Step 1: Scaffold a New Project
+
+Run the scaffolding command:
+
+```bash
+npx @esimplicitylabs/katalyst-xspec init
+```
+
+Options:
+- `--dir <name>` - Create in specific directory
+- `--force` - Overwrite existing files
+
+Example:
+```bash
+npx @esimplicitylabs/katalyst-xspec init --dir my-tests
+cd my-tests
+npm install
+```
+
+## Step 2: Understand the Project Structure
+
+The scaffold creates:
+
+```
+my-tests/
+├── features/
+│   ├── api/
+│   │   └── 00_api_examples.feature    # API test examples
+│   ├── ui/
+│   │   └── 00_ui_examples.feature     # UI test examples
+│   ├── hybrid/
+│   │   └── 00_hybrid_examples.feature # Combined API+UI tests
+│   ├── tui/
+│   │   └── 00_tui_examples.feature    # Terminal UI tests
+│   └── steps/
+│       ├── fixtures.ts                 # Adapter configuration
+│       └── steps.ts                    # Step registration
+├── playwright.config.ts                # BDD project config
+├── .env.example                        # Environment template
+├── tsconfig.json                       # TypeScript config
+└── package.json                        # Dependencies
+```
+
+### Key Files
+
+**`features/steps/fixtures.ts`** - Configures adapters:
+```typescript
+import { createBddTest } from '@esimplicitylabs/katalyst-xspec';
+
+export const test = createBddTest({
+  // Default adapters are used unless you customize
+});
+```
+
+**`features/steps/steps.ts`** - Registers step definitions:
+```typescript
+import { test } from './fixtures';
+import { registerAllSteps } from '@esimplicitylabs/katalyst-xspec/steps';
+
+registerAllSteps(test);
+
+export { test };
+```
+
+**`playwright.config.ts`** - Defines BDD projects:
+```typescript
+import { defineBddProject } from 'playwright-bdd';
+
+const apiBdd = defineBddProject({
+  name: 'api',
+  features: 'features/api/**/*.feature',
+  steps: 'features/steps/**/*.ts',
+  tags: '@api',
+});
+```
+
+## Step 3: Configure Environment
+
+Copy the environment template:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your settings:
+
+```bash
+# API Configuration
+API_BASE_URL=http://localhost:3000
+
+# Authentication (required -- no hardcoded defaults)
+DEFAULT_ADMIN_USERNAME=admin@example.com
+DEFAULT_ADMIN_PASSWORD=admin123
+DEFAULT_USER_USERNAME=user@example.com
+DEFAULT_USER_PASSWORD=user123
+API_AUTH_LOGIN_PATH=/auth/login
+
+# UI Configuration
+FRONTEND_URL=http://localhost:3000
+BASE_URL=http://localhost:3000
+HEADLESS=true
+
+# Cleanup Rules (required -- no built-in rules)
+# CLEANUP_RULES='[{"varMatch":"user","path":"/api/users/{id}"}]'
+```
+
+### Required Variables by Test Type
+
+| Test Type | Required Variables |
+|-----------|-------------------|
+| `@api` | `API_BASE_URL` |
+| `@ui` | `FRONTEND_URL` or `BASE_URL` |
+| `@hybrid` | Both API and UI variables |
+| Auth steps | `DEFAULT_*_USERNAME`, `DEFAULT_*_PASSWORD` |
+
+## Step 4: Write Your First Test
+
+### API Test
+
+Create `features/api/health.feature`:
+
+```gherkin
+@api
+Feature: Health Check
+
+  Scenario: API is healthy
+    When I GET "/health"
+    Then the response status should be 200
+```
+
+### UI Test
+
+Create `features/ui/home.feature`:
+
+```gherkin
+@ui
+Feature: Home Page
+
+  Scenario: Home page loads
+    Given I navigate to "/"
+    Then I should see text "Welcome"
+```
+
+### Hybrid Test
+
+Create `features/hybrid/workflow.feature`:
+
+```gherkin
+@hybrid
+Feature: User Workflow
+
+  Scenario: Create via API, verify in UI
+    Given I am authenticated as an admin via API
+    When I POST "/users" with JSON body:
+      """
+      { "name": "Test User" }
+      """
+    Then the response status should be 201
+    And I store the value at "id" as "userId"
+    
+    Given I navigate to "/users/{userId}"
+    Then I should see text "Test User"
+```
+
+## Step 5: Run Tests
+
+**IMPORTANT:** You must generate Playwright tests before running.
+
+```bash
+# 1. Generate tests from feature files (REQUIRED)
+npm run gen
+
+# 2. Run all tests
+npm test
+
+# 3. Run specific project
+npx playwright test --project=api
+npx playwright test --project=ui
+npx playwright test --project=hybrid
+```
+
+### Common Run Commands
+
+```bash
+# Run with specific tag
+npx playwright test --grep "@smoke"
+
+# Run single feature file
+npx playwright test features/api/users.feature
+
+# Debug mode (opens browser and pauses)
+npx playwright test --debug
+
+# UI mode (interactive test runner)
+npx playwright test --ui
+
+# Headed mode (see the browser)
+npx playwright test --headed
+
+# Run with verbose output
+npx playwright test --reporter=list
+```
+
+## Step 6: View Results
+
+After running tests, find reports at:
+
+| Report | Location |
+|--------|----------|
+| Cucumber HTML | `cucumber-report/index.html` |
+| Cucumber JSON | `cucumber-report/report.json` |
+| Playwright HTML | `playwright-report/index.html` |
+
+Open the Playwright report:
+```bash
+npx playwright show-report
+```
+
+## Common Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `@api` | API-only tests |
+| `@ui` | UI-only tests |
+| `@tui` | Terminal UI tests |
+| `@hybrid` | Combined API+UI tests |
+| `@smoke` | Quick smoke tests |
+| `@Skip` | Skip this scenario |
+| `@wip` | Work in progress |
+
+## Quick Reference: Essential Steps
+
+### API Steps
+```gherkin
+When I GET "/endpoint"
+When I POST "/endpoint" with JSON body:
+Then the response status should be 200
+And I store the value at "id" as "userId"
+```
+
+### UI Steps
+```gherkin
+Given I navigate to "/page"
+When I click the button "Submit"
+When I fill in "Email" with "test@example.com"
+Then I should see text "Success"
+```
+
+### Shared Steps
+```gherkin
+Given I generate a UUID and store as "runId"
+Given I set variable "name" to "value"
+Given I register cleanup DELETE "/resource/{id}"
+```
+
+## Troubleshooting Quick Fixes
+
+| Issue | Solution |
+|-------|----------|
+| "No tests found" | Run `npm run gen` first |
+| Steps not available | Check you have the correct tag |
+| Auth fails | Verify `.env` credentials |
+| Can't find element | Use `When I pause for debugging` |
+
+## Next Steps
+
+1. **Create more tests** - Add feature files to `features/api/`, `features/ui/`, etc.
+2. **Learn steps** - See full step reference with `katalyst-bdd-step-reference` skill
+3. **Patterns** - Learn test patterns with `katalyst-bdd-create-test` skill
+4. **Custom adapters** - Extend framework with `katalyst-bdd-architecture` skill
+
+## Upgrade Existing Project
+
+To upgrade an existing project to the latest version:
+
+```bash
+npx @esimplicitylabs/katalyst-xspec upgrade
+```
+
+This updates:
+- Package dependencies
+- Configuration templates
+- Step definitions