create-agent-skills 1.0.0 → 1.1.0

package/skills/maestro-testing/examples/checkout-flow.md

@@ -0,0 +1,246 @@
+# E-commerce Checkout Flow Example
+
+Complete checkout flow with scrolling, form filling, and payment.
+
+## Flow File: checkout-test.yaml
+
+```yaml
+appId: com.example.shop
+name: "User can complete checkout with credit card"
+tags:
+  - checkout
+  - payment
+  - e2e
+  - critical
+env:
+  CARD_NUMBER: "4111111111111111"
+  CARD_EXPIRY: "12/28"
+  CARD_CVV: "123"
+  SHIPPING_ADDRESS: "123 Main Street"
+  SHIPPING_CITY: "San Francisco"
+  SHIPPING_ZIP: "94102"
+---
+# Prerequisite: User is logged in and has items in cart
+- launchApp
+
+# Navigate to cart
+- tapOn:
+    id: "cart_icon"
+
+# Verify cart has items
+- assertVisible:
+    id: "cart_items_list"
+
+# Verify total is displayed
+- assertVisible: "Total: \\$[0-9]+\\.[0-9]{2}"
+
+# Proceed to checkout
+- tapOn:
+    id: "checkout_button"
+    enabled: true
+
+# === SHIPPING SECTION ===
+- assertVisible: "Shipping Address"
+
+# Fill shipping form
+- tapOn:
+    id: "address_input"
+- inputText: "${SHIPPING_ADDRESS}"
+
+- tapOn:
+    id: "city_input"
+- inputText: "${SHIPPING_CITY}"
+
+- tapOn:
+    id: "zip_input"
+- inputText: "${SHIPPING_ZIP}"
+
+- hideKeyboard
+
+# Scroll to continue button if needed
+- scrollUntilVisible:
+    element:
+      id: "continue_to_payment"
+    direction: DOWN
+
+- tapOn:
+    id: "continue_to_payment"
+
+# === PAYMENT SECTION ===
+- assertVisible: "Payment Method"
+
+# Select credit card
+- tapOn:
+    below: "Payment Method"
+    text: "Credit Card"
+
+# Fill card details
+- tapOn:
+    id: "card_number_input"
+- inputText: "${CARD_NUMBER}"
+
+- tapOn:
+    id: "card_expiry_input"
+- inputText: "${CARD_EXPIRY}"
+
+- tapOn:
+    id: "card_cvv_input"
+- inputText: "${CARD_CVV}"
+
+- hideKeyboard
+
+# === ORDER REVIEW ===
+- scrollUntilVisible:
+    element:
+      id: "place_order_button"
+    direction: DOWN
+
+# Verify order summary
+- assertVisible: "Order Summary"
+- assertVisible:
+    id: "order_total"
+
+# Take screenshot before placing order
+- takeScreenshot: "order_review"
+
+# Place order
+- tapOn:
+    id: "place_order_button"
+    enabled: true
+
+# Wait for order processing
+- extendedWaitUntil:
+    visible: "Order Confirmed"
+    timeout: 30000
+
+# Verify confirmation
+- assertVisible: "Order #[0-9]+"
+- assertVisible: "Thank you for your order"
+
+# Capture confirmation
+- takeScreenshot: "order_confirmation"
+```
+
+## Subflow: add-product-to-cart.yaml
+
+```yaml
+# subflows/add-product-to-cart.yaml
+# Requires PRODUCT_NAME and optional QUANTITY
+
+- scrollUntilVisible:
+    element: "${PRODUCT_NAME}"
+    direction: DOWN
+    timeout: 15000
+
+- tapOn: "${PRODUCT_NAME}"
+
+# Wait for product detail page
+- assertVisible:
+    id: "product_detail_screen"
+
+# Increase quantity if specified
+- runFlow:
+    when:
+      true: ${QUANTITY && QUANTITY > 1}
+    commands:
+      - repeat:
+          times: ${QUANTITY - 1}
+          commands:
+            - tapOn:
+                id: "quantity_increase"
+
+# Add to cart
+- tapOn:
+    id: "add_to_cart_button"
+
+# Verify added
+- assertVisible: "Added to cart"
+
+# Go back to continue shopping or proceed
+- back
+```
+
+## Using with Login Subflow
+
+```yaml
+appId: com.example.shop
+name: "Complete purchase flow from login to confirmation"
+tags:
+  - e2e
+  - purchase
+env:
+  EMAIL: customer@example.com
+  PASSWORD: CustomerPass123!
+  PRODUCT_NAME: "Blue Wireless Headphones"
+  QUANTITY: 1
+  CARD_NUMBER: "4111111111111111"
+  CARD_EXPIRY: "12/28"
+  CARD_CVV: "123"
+---
+- launchApp:
+    clearState: true
+
+# Login
+- runFlow:
+    file: ../subflows/login-steps.yaml
+    env:
+      EMAIL: ${EMAIL}
+      PASSWORD: ${PASSWORD}
+
+# Add product to cart
+- runFlow:
+    file: ../subflows/add-product-to-cart.yaml
+    env:
+      PRODUCT_NAME: ${PRODUCT_NAME}
+      QUANTITY: ${QUANTITY}
+
+# Go to cart and checkout
+- tapOn:
+    id: "cart_icon"
+
+- runFlow: ../subflows/checkout-steps.yaml
+```
+
+## Handling Cart Edge Cases
+
+```yaml
+appId: com.example.shop
+name: "Empty cart shows appropriate message"
+tags:
+  - cart
+  - edge-case
+---
+- launchApp:
+    clearState: true
+
+# Skip login for guest browsing
+- runFlow:
+    when:
+      visible: "Continue as Guest"
+    commands:
+      - tapOn: "Continue as Guest"
+
+# Navigate to cart
+- tapOn:
+    id: "cart_icon"
+
+# Verify empty cart state
+- assertVisible: "Your cart is empty"
+- assertVisible:
+    id: "start_shopping_button"
+
+# Checkout button should be disabled or hidden
+- assertNotVisible:
+    id: "checkout_button"
+    enabled: true
+```
+
+## Key Patterns Used
+
+1. **Scroll before interact** - `scrollUntilVisible` before tapping buttons at bottom
+2. **Form filling pattern** - Tap field → Input text → Next field
+3. **Regex assertions** - `"Order #[0-9]+"` for dynamic content
+4. **Conditional flows** - Handle optional UI elements
+5. **Screenshots at key points** - Before and after critical actions
+6. **Extended waits** - For payment processing (30s timeout)
+7. **Relative selectors** - `below: "Payment Method"` for context

package/skills/maestro-testing/examples/login-flow.md

@@ -0,0 +1,164 @@
+# Login Flow Example
+
+This example demonstrates a complete login flow test with best practices.
+
+## Flow File: login-test.yaml
+
+```yaml
+appId: com.example.myapp
+name: "User can login with valid credentials"
+tags:
+  - smoke
+  - auth
+  - critical
+env:
+  TEST_EMAIL: testuser@example.com
+  TEST_PASSWORD: SecurePass123!
+---
+# Start fresh
+- launchApp:
+    clearState: true
+
+# Wait for app to load
+- assertVisible:
+    id: "splash_screen"
+    optional: true
+- extendedWaitUntil:
+    visible:
+      id: "login_screen"
+    timeout: 10000
+
+# Enter email
+- tapOn:
+    id: "email_input"
+- inputText: "${TEST_EMAIL}"
+
+# Enter password
+- tapOn:
+    id: "password_input"
+- inputText: "${TEST_PASSWORD}"
+
+# Hide keyboard if needed
+- hideKeyboard
+
+# Submit login
+- tapOn:
+    id: "login_button"
+    enabled: true
+
+# Wait for login to complete
+- extendedWaitUntil:
+    visible:
+      id: "home_screen"
+    timeout: 15000
+
+# Verify successful login
+- assertVisible: "Welcome back"
+- assertVisible:
+    id: "user_profile_icon"
+
+# Take screenshot for report
+- takeScreenshot: "login_success"
+```
+
+## Subflow: login-steps.yaml
+
+Reusable login component for other tests:
+
+```yaml
+# subflows/login-steps.yaml
+# Requires EMAIL and PASSWORD env variables from parent flow
+
+- tapOn:
+    id: "email_input"
+- inputText: "${EMAIL}"
+
+- tapOn:
+    id: "password_input"  
+- inputText: "${PASSWORD}"
+
+- hideKeyboard
+
+- tapOn:
+    id: "login_button"
+
+- extendedWaitUntil:
+    visible:
+      id: "home_screen"
+    timeout: 15000
+```
+
+## Using the Subflow
+
+```yaml
+appId: com.example.myapp
+name: "User can access settings after login"
+env:
+  EMAIL: testuser@example.com
+  PASSWORD: SecurePass123!
+---
+- launchApp:
+    clearState: true
+
+# Reuse login subflow
+- runFlow: ../subflows/login-steps.yaml
+
+# Continue with test-specific steps
+- tapOn:
+    id: "menu_button"
+- tapOn: "Settings"
+- assertVisible: "Account Settings"
+```
+
+## Handling Login Errors
+
+```yaml
+appId: com.example.myapp
+name: "Invalid login shows error message"
+tags:
+  - auth
+  - negative
+env:
+  INVALID_EMAIL: wrong@example.com
+  INVALID_PASSWORD: wrongpassword
+---
+- launchApp:
+    clearState: true
+
+- tapOn:
+    id: "email_input"
+- inputText: "${INVALID_EMAIL}"
+
+- tapOn:
+    id: "password_input"
+- inputText: "${INVALID_PASSWORD}"
+
+- tapOn:
+    id: "login_button"
+
+# Verify error is shown
+- assertVisible:
+    text: "Invalid email or password"
+- assertVisible:
+    id: "error_banner"
+
+# Verify still on login screen
+- assertVisible:
+    id: "login_screen"
+
+# Verify login button still available (not navigated away)
+- assertVisible:
+    id: "login_button"
+    enabled: true
+```
+
+## Best Practices Applied
+
+1. **Clear state** - Start fresh with `clearState: true`
+2. **Use IDs** - `id: "login_button"` instead of text
+3. **Environment variables** - Credentials in `env` section
+4. **Explicit waits** - `extendedWaitUntil` for async operations
+5. **Screenshots** - Capture proof of success
+6. **Subflows** - Reusable login component
+7. **Meaningful tags** - `smoke`, `auth`, `critical`
+8. **Descriptive names** - Clear test intent

package/skills/maestro-testing/examples/project-structure.md

@@ -0,0 +1,245 @@
+# Project Structure Template
+
+Recommended Maestro test project structure for maintainable test suites.
+
+## Directory Structure
+
+```
+project-root/
+├── .maestro/
+│   ├── config.yaml              # Workspace configuration
+│   ├── flows/                   # Test flows (runnable tests)
+│   │   ├── auth/
+│   │   │   ├── login.yaml
+│   │   │   ├── logout.yaml
+│   │   │   ├── forgot-password.yaml
+│   │   │   └── register.yaml
+│   │   ├── onboarding/
+│   │   │   ├── first-time-user.yaml
+│   │   │   └── skip-onboarding.yaml
+│   │   ├── checkout/
+│   │   │   ├── guest-checkout.yaml
+│   │   │   ├── member-checkout.yaml
+│   │   │   └── failed-payment.yaml
+│   │   └── profile/
+│   │       ├── edit-profile.yaml
+│   │       └── change-password.yaml
+│   ├── subflows/                # Reusable components (not run directly)
+│   │   ├── auth/
+│   │   │   ├── login-steps.yaml
+│   │   │   ├── logout-steps.yaml
+│   │   │   └── fill-registration-form.yaml
+│   │   ├── navigation/
+│   │   │   ├── go-to-home.yaml
+│   │   │   ├── go-to-cart.yaml
+│   │   │   ├── go-to-profile.yaml
+│   │   │   └── go-to-settings.yaml
+│   │   ├── common/
+│   │   │   ├── dismiss-popups.yaml
+│   │   │   ├── accept-cookies.yaml
+│   │   │   └── handle-permissions.yaml
+│   │   └── cart/
+│   │       ├── add-to-cart.yaml
+│   │       ├── remove-from-cart.yaml
+│   │       └── update-quantity.yaml
+│   └── scripts/                 # JavaScript helpers
+│       ├── data-generators.js
+│       ├── date-helpers.js
+│       └── api-helpers.js
+├── test-results/                # Output directory (gitignored)
+│   ├── screenshots/
+│   ├── recordings/
+│   └── reports/
+└── .gitignore
+```
+
+## config.yaml
+
+```yaml
+# .maestro/config.yaml
+
+# Include all flows, exclude work-in-progress
+flows:
+  - 'flows/**/*.yaml'
+  - '!flows/**/*-wip.yaml'
+  - '!flows/**/*.draft.yaml'
+
+# Default tags to include/exclude
+includeTags: []                  # Empty = include all
+excludeTags:
+  - flaky
+  - manual
+
+# Execution order for dependent tests
+executionOrder:
+  continueOnFailure: false       # Stop on first failure for CI
+  flowsOrder:
+    - flows/auth/login.yaml      # Login first
+    - flows/onboarding/*.yaml    # Then onboarding
+
+# Output directory
+testOutputDir: ../test-results
+
+# Platform settings
+platform:
+  ios:
+    disableAnimations: true
+    snapshotKeyHonorModalViews: false
+  android:
+    disableAnimations: true
+```
+
+## PR-specific config: pr-config.yaml
+
+```yaml
+# .maestro/pr-config.yaml
+# Faster subset for pull request checks
+
+flows:
+  - 'flows/**/*.yaml'
+
+includeTags:
+  - smoke
+  - critical
+
+excludeTags:
+  - slow
+  - flaky
+
+executionOrder:
+  continueOnFailure: true        # Run all tests, report failures
+```
+
+## Subflow Template
+
+```yaml
+# .maestro/subflows/auth/login-steps.yaml
+#
+# Reusable login component
+# Required env: EMAIL, PASSWORD
+# Assumes: App is launched and on login screen
+
+- tapOn:
+    id: "email_input"
+- inputText: "${EMAIL}"
+
+- tapOn:
+    id: "password_input"
+- inputText: "${PASSWORD}"
+
+- hideKeyboard
+
+- tapOn:
+    id: "login_button"
+
+- extendedWaitUntil:
+    visible:
+      id: "home_screen"
+    timeout: 15000
+```
+
+## Flow Template
+
+```yaml
+# .maestro/flows/auth/login.yaml
+
+appId: com.example.myapp
+name: "User can login with valid credentials"
+tags:
+  - auth
+  - smoke
+  - critical
+env:
+  EMAIL: testuser@example.com
+  PASSWORD: TestPass123!
+---
+# Setup
+- launchApp:
+    clearState: true
+
+# Handle any initial popups
+- runFlow:
+    when:
+      visible: "Allow Notifications"
+    file: ../../subflows/common/handle-permissions.yaml
+
+# Execute login
+- runFlow:
+    file: ../../subflows/auth/login-steps.yaml
+
+# Verify success
+- assertVisible: "Welcome"
+- assertVisible:
+    id: "home_screen"
+
+# Capture result
+- takeScreenshot: "login_success"
+```
+
+## .gitignore
+
+```gitignore
+# Maestro test outputs
+test-results/
+*.mp4
+*.png
+
+# Local environment overrides
+.maestro/config.local.yaml
+
+# IDE
+.idea/
+.vscode/
+```
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Flows | `action-subject.yaml` | `login.yaml`, `add-to-cart.yaml` |
+| Subflows | `action-steps.yaml` | `login-steps.yaml`, `checkout-steps.yaml` |
+| Directories | lowercase, plural | `flows/`, `subflows/`, `scripts/` |
+| Tags | lowercase, hyphenated | `smoke`, `e2e`, `auth`, `critical` |
+
+## Tag Strategy
+
+```yaml
+# Execution tags
+- smoke          # Quick sanity tests (~5 min)
+- e2e           # Full end-to-end flows
+- critical      # Must pass for release
+
+# Feature tags
+- auth          # Authentication flows
+- checkout      # Purchase flows
+- profile       # User profile tests
+
+# Filter tags
+- flaky         # Known flaky tests
+- slow          # Long-running tests
+- manual        # Require manual intervention
+- wip           # Work in progress
+```
+
+## Running Tests
+
+```bash
+# All tests
+maestro test .maestro/flows/
+
+# With workspace config
+maestro test --config .maestro/config.yaml .maestro/flows/
+
+# PR config (smoke tests only)
+maestro test --config .maestro/pr-config.yaml .maestro/flows/
+
+# Specific feature
+maestro test .maestro/flows/auth/
+
+# By tags
+maestro test --include-tags=smoke,critical .maestro/flows/
+maestro test --exclude-tags=flaky,slow .maestro/flows/
+
+# Continuous mode for development
+maestro test --continuous .maestro/flows/auth/login.yaml
+```