@esimplicitylabs/katalyst-xspec 0.6.0

package/skills/katalyst-bdd-step-reference/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: katalyst-bdd-step-reference
+description: Complete reference of all available BDD step definitions in the Katalyst framework. Use when writing feature files, looking up step syntax, understanding what steps are available for a tag, or finding the right step for a specific action like clicking, filling forms, making API calls, or terminal interactions.
+---
+
+# Katalyst BDD Step Reference
+
+This skill provides a complete reference of all step definitions available in @esimplicitylabs/katalyst-xspec.
+
+## Tag System
+
+Steps are enabled based on the feature/scenario tag:
+
+| Tag | Available Steps | Use Case |
+|-----|-----------------|----------|
+| `@api` | API + Shared | HTTP API testing only |
+| `@ui` | UI + Shared | Browser UI testing only |
+| `@tui` | TUI + Shared | Terminal UI testing only |
+| `@hybrid` | API + UI + Shared | Combined API and UI testing |
+
+**Important:** Always tag your feature or scenario. Without a tag, steps may not be available.
+
+## Variable Interpolation
+
+All steps support variable interpolation using `{varName}` syntax:
+
+```gherkin
+Given I set variable "userId" to "123"
+When I GET "/users/{userId}"  # Becomes /users/123
+```
+
+## Quick Reference - Most Common Steps
+
+### API Steps (`@api` or `@hybrid`)
+
+| Step | Example |
+|------|---------|
+| `When I GET {string}` | `When I GET "/users"` |
+| `When I POST {string} with JSON body:` | `When I POST "/users" with JSON body:` + docstring |
+| `When I PUT {string} with JSON body:` | `When I PUT "/users/1" with JSON body:` + docstring |
+| `When I PATCH {string} with JSON body:` | `When I PATCH "/users/1" with JSON body:` + docstring |
+| `When I DELETE {string}` | `When I DELETE "/users/1"` |
+| `Then the response status should be {int}` | `Then the response status should be 200` |
+| `Then the response should be a JSON array` | Asserts response is an array |
+| `Then the response should be a JSON object` | Asserts response is an object |
+| `Then the value at {string} should equal {string}` | `Then the value at "name" should equal "John"` |
+| `And I store the value at {string} as {string}` | `And I store the value at "id" as "userId"` |
+| `Given I am authenticated as an admin via API` | Admin API authentication |
+| `Given I am authenticated as a user via API` | User API authentication |
+| `Given I set header {string} to {string}` | `Given I set header "X-Custom" to "value"` |
+
+### UI Steps (`@ui` or `@hybrid`)
+
+| Step | Example |
+|------|---------|
+| `Given I navigate to {string}` | `Given I navigate to "/login"` |
+| `When I click the button {string}` | `When I click the button "Submit"` |
+| `When I click the link {string}` | `When I click the link "Sign Up"` |
+| `When I fill the field {string} with {string}` | `When I fill the field "Email" with "test@example.com"` |
+| `When I fill in {string} with {string}` | `When I fill in "Password" with "secret"` |
+| `When I select {string} from dropdown {string}` | `When I select "Admin" from dropdown "Role"` |
+| `Then I should see text {string}` | `Then I should see text "Welcome"` |
+| `Then the URL should contain {string}` | `Then the URL should contain "/dashboard"` |
+| `Then the element {string} should be visible` | `Then the element "#modal" should be visible` |
+| `When I pause for debugging` | Opens Playwright Inspector |
+
+### TUI Steps (`@tui`)
+
+| Step | Example |
+|------|---------|
+| `Given I start the TUI application` | Starts the configured TUI app |
+| `When I type {string}` | `When I type "hello world"` |
+| `When I press {string}` | `When I press "Enter"` |
+| `When I press enter` | Press Enter key |
+| `Then I should see {string}` | `Then I should see "Welcome"` |
+| `Then the screen should contain {string}` | Assert screen has text |
+
+### Shared Steps (All Tags)
+
+| Step | Example |
+|------|---------|
+| `Given I set variable {string} to {string}` | `Given I set variable "email" to "test@test.com"` |
+| `Given I generate a UUID and store as {string}` | `Given I generate a UUID and store as "runId"` |
+| `Given I register cleanup DELETE {string}` | `Given I register cleanup DELETE "/users/{userId}"` |
+
+## Detailed Reference
+
+For complete step definitions with all parameters and examples:
+
+- [API Steps](references/api-steps.md) - HTTP methods, assertions, authentication
+- [UI Steps](references/ui-steps.md) - Navigation, clicks, forms, assertions
+- [TUI Steps](references/tui-steps.md) - Terminal input, output, snapshots
+- [Shared Steps](references/shared-steps.md) - Variables, cleanup, feature flags
+
+## Step Parameters
+
+| Placeholder | Type | Example |
+|-------------|------|---------|
+| `{string}` | Text in quotes | `"hello"` or `"/api/users"` |
+| `{int}` | Integer | `200`, `404` |
+| Docstring | Multi-line text | Triple quotes `"""` |
+| DataTable | Tabular data | Gherkin table format |
+
+## Common Patterns
+
+### API CRUD Test
+
+```gherkin
+@api
+Scenario: Create and fetch user
+  Given I am authenticated as an admin via API
+  When I POST "/users" with JSON body:
+    """
+    { "email": "test@example.com", "name": "Test" }
+    """
+  Then the response status should be 201
+  And I store the value at "id" as "userId"
+  When I GET "/users/{userId}"
+  Then the response status should be 200
+```
+
+### UI Login Test
+
+```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 "Dashboard"
+```
+
+### Hybrid Test (API + UI)
+
+```gherkin
+@hybrid
+Scenario: Create via API, verify in UI
+  Given I am authenticated as an admin via API
+  When I POST "/users" with JSON body:
+    """
+    { "email": "new@example.com" }
+    """
+  Then the response status should be 201
+  Given I navigate to "/admin/users"
+  Then I should see text "new@example.com"
+```

package/skills/katalyst-bdd-step-reference/references/api-steps.md

@@ -0,0 +1,247 @@
+# API Steps Reference
+
+Complete reference for API steps. Available in `@api` and `@hybrid` scenarios.
+
+## HTTP Method Steps
+
+### GET Request
+
+```gherkin
+When I GET {string}
+```
+
+**Example:**
+```gherkin
+When I GET "/users"
+When I GET "/users/{userId}"
+```
+
+### POST Request with JSON
+
+```gherkin
+When I POST {string} with JSON body:
+  """
+  { JSON content }
+  """
+```
+
+**Example:**
+```gherkin
+When I POST "/users" with JSON body:
+  """
+  {
+    "email": "test@example.com",
+    "name": "Test User",
+    "role": "member"
+  }
+  """
+```
+
+### PUT Request with JSON
+
+```gherkin
+When I PUT {string} with JSON body:
+  """
+  { JSON content }
+  """
+```
+
+**Example:**
+```gherkin
+When I PUT "/users/{userId}" with JSON body:
+  """
+  {
+    "name": "Updated Name"
+  }
+  """
+```
+
+### PATCH Request with JSON
+
+```gherkin
+When I PATCH {string} with JSON body:
+  """
+  { JSON content }
+  """
+```
+
+**Example:**
+```gherkin
+When I PATCH "/users/{userId}" with JSON body:
+  """
+  {
+    "status": "active"
+  }
+  """
+```
+
+### DELETE Request
+
+```gherkin
+When I DELETE {string}
+```
+
+**Example:**
+```gherkin
+When I DELETE "/users/{userId}"
+```
+
+## Authentication Steps
+
+### Admin Authentication
+
+```gherkin
+Given I am authenticated as an admin via API
+```
+
+Uses `DEFAULT_ADMIN_USERNAME` and `DEFAULT_ADMIN_PASSWORD` env variables.
+
+### User Authentication
+
+```gherkin
+Given I am authenticated as a user via API
+```
+
+Uses `DEFAULT_USER_USERNAME` and `DEFAULT_USER_PASSWORD` env variables.
+
+### Set Bearer Token
+
+```gherkin
+Given I set bearer token from variable {string}
+```
+
+**Example:**
+```gherkin
+Given I set bearer token from variable "authToken"
+```
+
+### Set Custom Header
+
+```gherkin
+Given I set header {string} to {string}
+```
+
+**Example:**
+```gherkin
+Given I set header "X-API-Key" to "abc123"
+Given I set header "Authorization" to "Bearer {token}"
+```
+
+## Response Assertion Steps
+
+### Assert Status Code
+
+```gherkin
+Then the response status should be {int}
+```
+
+**Example:**
+```gherkin
+Then the response status should be 200
+Then the response status should be 201
+Then the response status should be 404
+```
+
+### Assert JSON Type
+
+```gherkin
+Then the response should be a JSON array
+Then the response should be a JSON object
+```
+
+### Assert JSON Value
+
+```gherkin
+Then the value at {string} should equal {string}
+```
+
+Uses JSON path syntax for nested values.
+
+**Example:**
+```gherkin
+Then the value at "id" should equal "123"
+Then the value at "user.name" should equal "John"
+Then the value at "items[0].id" should equal "1"
+Then the value at "data.users[0].email" should equal "{expectedEmail}"
+```
+
+### Assert Value Contains
+
+```gherkin
+Then the value at {string} should contain {string}
+```
+
+**Example:**
+```gherkin
+Then the value at "message" should contain "success"
+```
+
+### Assert Value Matches Pattern
+
+```gherkin
+Then the value at {string} should match {string}
+```
+
+**Example:**
+```gherkin
+Then the value at "email" should match "^[a-z]+@example\\.com$"
+```
+
+## Value Extraction Steps
+
+### Store Response Value
+
+```gherkin
+And I store the value at {string} as {string}
+```
+
+Extracts a value from the JSON response and stores it in a variable.
+
+**Example:**
+```gherkin
+And I store the value at "id" as "userId"
+And I store the value at "data.token" as "authToken"
+And I store the value at "items[0].id" as "firstItemId"
+```
+
+## Complete API Example
+
+```gherkin
+@api
+Feature: User Management API
+
+  Background:
+    Given I am authenticated as an admin via API
+
+  Scenario: Full CRUD lifecycle
+    # Create
+    Given I generate a UUID and store as "runId"
+    When I POST "/admin/users" with JSON body:
+      """
+      {
+        "email": "test-{runId}@example.com",
+        "name": "Test User {runId}",
+        "role": "member"
+      }
+      """
+    Then the response status should be 201
+    And I store the value at "id" as "userId"
+    And the value at "email" should equal "test-{runId}@example.com"
+    
+    # Read
+    When I GET "/admin/users/{userId}"
+    Then the response status should be 200
+    And the value at "name" should contain "Test User"
+    
+    # Update
+    When I PATCH "/admin/users/{userId}" with JSON body:
+      """
+      { "name": "Updated User" }
+      """
+    Then the response status should be 200
+    And the value at "name" should equal "Updated User"
+    
+    # Delete
+    When I DELETE "/admin/users/{userId}"
+    Then the response status should be 204
+```