qa-skills 3.0.0

package/skills/qa-selenium-py-writer/references/config.md

@@ -0,0 +1,224 @@
+# Selenium Python Configuration
+
+Setup and configuration for Selenium WebDriver with Python.
+
+## Dependencies
+
+```bash
+pip install selenium
+pip install webdriver-manager  # Optional: auto-manage driver binaries
+pip install pytest  # For test runner
+```
+
+## WebDriver Manager (Recommended)
+
+Automatically downloads and manages ChromeDriver, GeckoDriver, etc.:
+
+```python
+from selenium import webdriver
+from webdriver_manager.chrome import ChromeDriverManager
+from selenium.webdriver.chrome.service import Service
+
+service = Service(ChromeDriverManager().install())
+driver = webdriver.Chrome(service=service)
+```
+
+```python
+# Firefox
+from webdriver_manager.firefox import GeckoDriverManager
+service = Service(GeckoDriverManager().install())
+driver = webdriver.Firefox(service=service)
+```
+
+```python
+# Edge
+from webdriver_manager.microsoft import EdgeChromiumDriverManager
+service = Service(EdgeChromiumDriverManager().install())
+driver = webdriver.Edge(service=service)
+```
+
+## Browser Options
+
+### Chrome
+
+```python
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+
+options = Options()
+options.add_argument("--headless")
+options.add_argument("--no-sandbox")
+options.add_argument("--disable-dev-shm-usage")
+options.add_argument("--disable-gpu")
+options.add_argument("--window-size=1920,1080")
+
+driver = webdriver.Chrome(options=options)
+```
+
+### Firefox
+
+```python
+from selenium import webdriver
+from selenium.webdriver.firefox.options import Options
+
+options = Options()
+options.add_argument("--headless")
+
+driver = webdriver.Firefox(options=options)
+```
+
+### Edge
+
+```python
+from selenium import webdriver
+from selenium.webdriver.edge.options import Options
+
+options = Options()
+options.add_argument("--headless")
+
+driver = webdriver.Edge(options=options)
+```
+
+## Pytest Integration
+
+### conftest.py (Driver Fixture)
+
+```python
+# tests/conftest.py
+import pytest
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+from webdriver_manager.chrome import ChromeDriverManager
+from selenium.webdriver.chrome.service import Service
+
+
+@pytest.fixture(scope="function")
+def driver():
+    options = Options()
+    options.add_argument("--headless")
+    options.add_argument("--no-sandbox")
+    options.add_argument("--disable-dev-shm-usage")
+    service = Service(ChromeDriverManager().install())
+    driver = webdriver.Chrome(service=service, options=options)
+    yield driver
+    driver.quit()
+
+
+@pytest.fixture(scope="function")
+def driver_visible():
+    """Non-headless for local debugging."""
+    service = Service(ChromeDriverManager().install())
+    driver = webdriver.Chrome(service=service)
+    yield driver
+    driver.quit()
+```
+
+### Test Module
+
+```python
+# tests/test_login.py
+import pytest
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+
+
+def test_login_success(driver):
+    driver.get("https://example.com/login")
+    driver.find_element(By.ID, "username").send_keys("user")
+    driver.find_element(By.ID, "password").send_keys("pass")
+    driver.find_element(By.CSS_SELECTOR, "button[type='submit']").click()
+
+    WebDriverWait(driver, 10).until(EC.url_contains("dashboard"))
+    assert "dashboard" in driver.current_url
+```
+
+## Headless Configuration
+
+| Browser | Headless Flag |
+| ------- | ------------- |
+| Chrome | `--headless=new` or `--headless` |
+| Firefox | `--headless` |
+| Edge | `--headless` |
+
+```python
+def get_headless_chrome():
+    options = Options()
+    options.add_argument("--headless=new")
+    options.add_argument("--no-sandbox")
+    options.add_argument("--disable-dev-shm-usage")
+    options.add_argument("--disable-gpu")
+    options.add_argument("--window-size=1920,1080")
+    return webdriver.Chrome(options=options)
+```
+
+## Environment-Based Config
+
+```python
+import os
+
+def create_driver():
+    browser = os.getenv("SELENIUM_BROWSER", "chrome")
+    headless = os.getenv("SELENIUM_HEADLESS", "true").lower() == "true"
+
+    if browser == "chrome":
+        options = Options()
+        if headless:
+            options.add_argument("--headless=new")
+        return webdriver.Chrome(options=options)
+    elif browser == "firefox":
+        options = webdriver.FirefoxOptions()
+        if headless:
+            options.add_argument("--headless")
+        return webdriver.Firefox(options=options)
+    else:
+        raise ValueError(f"Unsupported browser: {browser}")
+```
+
+## Base URL Fixture
+
+```python
+# conftest.py
+@pytest.fixture(scope="session")
+def base_url():
+    return os.getenv("BASE_URL", "https://example.com")
+
+
+@pytest.fixture
+def login_page(driver, base_url):
+    from pages.login import LoginPage
+    return LoginPage(driver, base_url)
+```
+
+## Timeouts
+
+```python
+# Page load timeout
+driver.set_page_load_timeout(30)
+
+# Script timeout (async scripts)
+driver.set_script_timeout(10)
+
+# Implicit wait (use sparingly)
+driver.implicitly_wait(5)
+```
+
+## pyproject.toml / pytest.ini
+
+```toml
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+markers = [
+    "e2e: end-to-end Selenium tests",
+    "slow: slow-running tests",
+]
+```
+
+```bash
+# Run only E2E tests
+pytest -m e2e
+
+# Run with visible browser
+SELENIUM_HEADLESS=false pytest tests/
+```

package/skills/qa-selenium-py-writer/references/patterns.md

@@ -0,0 +1,255 @@
+# Selenium Python Patterns
+
+Common patterns for E2E testing with Selenium WebDriver in Python.
+
+## Locators
+
+| Strategy | Example | When to Use |
+| -------- | ------- | ----------- |
+| By.ID | `driver.find_element(By.ID, "username")` | Unique ID attribute |
+| By.CSS_SELECTOR | `driver.find_element(By.CSS_SELECTOR, "button.submit")` | Complex selectors |
+| By.XPATH | `driver.find_element(By.XPATH, "//button[text()='Submit']")` | Text, hierarchy, axes |
+| By.NAME | `driver.find_element(By.NAME, "email")` | Form inputs by name |
+| By.CLASS_NAME | `driver.find_element(By.CLASS_NAME, "btn-primary")` | Single class |
+| By.LINK_TEXT | `driver.find_element(By.LINK_TEXT, "Sign in")` | Exact link text |
+| By.PARTIAL_LINK_TEXT | `driver.find_element(By.PARTIAL_LINK_TEXT, "Sign")` | Partial link text |
+| By.TAG_NAME | `driver.find_element(By.TAG_NAME, "input")` | Tag type |
+
+```python
+from selenium.webdriver.common.by import By
+
+element = driver.find_element(By.ID, "submit-btn")
+elements = driver.find_elements(By.CSS_SELECTOR, ".list-item")
+```
+
+## Waits
+
+### Explicit Wait (Preferred)
+
+```python
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+
+# Wait for element to be visible
+element = WebDriverWait(driver, 10).until(
+    EC.visibility_of_element_located((By.ID, "username"))
+)
+
+# Wait for element to be clickable
+button = WebDriverWait(driver, 10).until(
+    EC.element_to_be_clickable((By.CSS_SELECTOR, "button.submit"))
+)
+
+# Wait for URL change
+WebDriverWait(driver, 10).until(EC.url_contains("dashboard"))
+
+# Wait for element to be present in DOM
+element = WebDriverWait(driver, 10).until(
+    EC.presence_of_element_located((By.ID, "results"))
+)
+```
+
+### Common Expected Conditions
+
+| Condition | Use Case |
+| --------- | -------- |
+| `visibility_of_element_located` | Element visible and has dimensions |
+| `element_to_be_clickable` | Element visible and enabled |
+| `presence_of_element_located` | Element in DOM (may be hidden) |
+| `text_to_be_present_in_element` | Specific text in element |
+| `url_contains` | URL contains substring |
+| `title_is` | Page title exact match |
+| `alert_is_present` | Alert dialog present |
+
+### Implicit Wait (Use Sparingly)
+
+```python
+# Sets default wait for find_element; applies to all subsequent calls
+driver.implicitly_wait(10)  # Seconds
+```
+
+**Note:** Prefer explicit waits. Implicit waits can cause unexpected delays and mask timing issues.
+
+## Page Object Model (POM)
+
+```python
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+
+class LoginPage:
+    def __init__(self, driver, base_url):
+        self.driver = driver
+        self.base_url = base_url
+
+    @property
+    def username_input(self):
+        return WebDriverWait(self.driver, 10).until(
+            EC.visibility_of_element_located((By.ID, "username"))
+        )
+
+    @property
+    def password_input(self):
+        return self.driver.find_element(By.ID, "password")
+
+    @property
+    def submit_button(self):
+        return self.driver.find_element(By.CSS_SELECTOR, "button[type='submit']")
+
+    def open(self):
+        self.driver.get(f"{self.base_url}/login")
+
+    def login(self, username: str, password: str):
+        self.open()
+        self.username_input.send_keys(username)
+        self.password_input.send_keys(password)
+        self.submit_button.click()
+```
+
+## ActionChains (Complex Interactions)
+
+```python
+from selenium.webdriver.common.action_chains import ActionChains
+
+# Hover
+actions = ActionChains(driver)
+actions.move_to_element(menu_element).perform()
+
+# Click and hold, drag and drop
+actions = ActionChains(driver)
+actions.click_and_hold(source).move_to_element(target).release().perform()
+
+# Double click
+actions = ActionChains(driver)
+actions.double_click(element).perform()
+
+# Right click (context menu)
+actions = ActionChains(driver)
+actions.context_click(element).perform()
+
+# Send keys with modifier
+actions = ActionChains(driver)
+actions.key_down(Keys.CONTROL).send_keys("a").key_up(Keys.CONTROL).perform()
+
+# Chain multiple actions
+actions = ActionChains(driver)
+actions.move_to_element(menu).click(hidden_submenu).perform()
+```
+
+## Select (Dropdowns)
+
+```python
+from selenium.webdriver.support.ui import Select
+
+select = Select(driver.find_element(By.ID, "country"))
+
+# By value
+select.select_by_value("us")
+
+# By visible text
+select.select_by_visible_text("United States")
+
+# By index (0-based)
+select.select_by_index(0)
+
+# Get options
+options = select.options
+first_selected = select.first_selected_option.text
+
+# Deselect (multi-select only)
+select.deselect_all()
+select.deselect_by_visible_text("Option A")
+```
+
+## File Upload
+
+```python
+# Input type="file" - send path directly
+file_input = driver.find_element(By.CSS_SELECTOR, "input[type='file']")
+file_input.send_keys("/absolute/path/to/file.pdf")
+
+# Multiple files (if supported)
+file_input.send_keys("/path/file1.pdf\n/path/file2.pdf")
+```
+
+## Alerts
+
+```python
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+
+# Wait for alert and accept
+WebDriverWait(driver, 10).until(EC.alert_is_present())
+alert = driver.switch_to.alert
+alert.accept()  # OK
+# alert.dismiss()  # Cancel
+# text = alert.text  # Get message
+# alert.send_keys("input")  # For prompt()
+```
+
+## Frames
+
+```python
+# Switch to frame by index, name, or element
+driver.switch_to.frame(0)  # First frame
+driver.switch_to.frame("frame-name")
+driver.switch_to.frame(frame_element)
+
+# Switch back to main content
+driver.switch_to.default_content()
+
+# Switch to parent frame (nested frames)
+driver.switch_to.parent_frame()
+```
+
+## Windows / Tabs
+
+```python
+# Get current window handle
+current = driver.current_window_handle
+
+# Get all window handles
+handles = driver.window_handles
+
+# Switch to new tab/window
+driver.switch_to.window(handles[-1])
+
+# Close current and switch back
+driver.close()
+driver.switch_to.window(handles[0])
+```
+
+## Basic Interactions
+
+```python
+# Navigation
+driver.get("https://example.com")
+driver.back()
+driver.forward()
+driver.refresh()
+
+# Element interactions
+element.click()
+element.send_keys("text")
+element.clear()
+element.submit()  # Form submit
+
+# Get attributes and text
+text = element.text
+value = element.get_attribute("value")
+href = element.get_attribute("href")
+is_displayed = element.is_displayed()
+is_enabled = element.is_enabled()
+```
+
+## Keys
+
+```python
+from selenium.webdriver.common.keys import Keys
+
+element.send_keys(Keys.ENTER)
+element.send_keys(Keys.TAB)
+element.send_keys(Keys.ESCAPE)
+element.send_keys(Keys.ARROW_DOWN)
+element.send_keys(Keys.CONTROL + "a")  # Select all
+```

package/skills/qa-shortcut-integration/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: qa-shortcut-integration
+description: Shortcut (formerly Clubhouse) integration for creating stories, managing epics/iterations, and tracking QA workflows via REST API.
+dependencies:
+  recommended:
+    - qa-bug-ticket-creator
+    - qa-task-creator
+---
+
+# QA Shortcut Integration
+
+## Purpose
+
+Integrate QA workflow with Shortcut for project management. Create and update stories from bug reports, test coverage gaps, and QA tasks. Sync QA metadata (severity, test type, labels) with Shortcut epics, iterations, and workflow states.
+
+## Primary Target
+
+**Shortcut** (formerly Clubhouse) via REST API v3. Base URL: `https://api.app.shortcut.com/api/v3`.
+
+## Features
+
+### Create/Update Stories
+
+- **Create** stories in projects with full metadata
+- **Update** existing stories (status, labels, description, external links)
+- **Search** stories by query, epic, iteration, or label
+
+### Epics and Iterations
+
+- **Epics** — Group stories by feature/release; link stories to epics
+- **Iterations** — Assign stories to sprints; query by iteration
+- **Workflow states** — Map QA status to Shortcut workflow states
+
+### Labels and Story Types
+
+- **Story types** — Bug, feature, chore (map from QA task type)
+- **Labels** — Component, severity, test type, coverage area
+- **Custom fields** — Use Shortcut custom fields for QA metadata when configured
+
+### Story Relationships
+
+- **Blocking / blocked by** — Link stories for dependencies
+- **External links** — Link to test cases, requirements, coverage reports
+- **Comments** — Add reproduction steps, evidence, verification notes
+
+## Authentication
+
+| Variable | Description |
+| -------- | ----------- |
+| `SHORTCUT_API_TOKEN` | API token from Shortcut Settings → Account → API Tokens |
+
+Store in `.env`; never hardcode. Header: `Shortcut-Token: <token>`.
+
+## Key API Endpoints
+
+| Method | Endpoint | Use |
+| ------ | -------- | --- |
+| POST | `/api/v3/stories` | Create story |
+| GET | `/api/v3/stories/{story_id}` | Get story |
+| PUT | `/api/v3/stories/{story_id}` | Update story |
+| GET | `/api/v3/search/stories` | Search stories (query, epic, iteration) |
+| GET | `/api/v3/epics` | List epics |
+| GET | `/api/v3/iterations` | List iterations |
+| GET | `/api/v3/workflows` | List workflow states |
+
+See `references/api-patterns.md` for request/response patterns.
+
+## Integration with QA Skills
+
+| Skill | Integration |
+| ----- | ----------- |
+| **qa-bug-ticket-creator** | Create Shortcut story from bug report; map severity/priority to labels |
+| **qa-task-creator** | Create Shortcut story from QA task; link to epic/iteration |
+| **qa-coverage-analyzer** | Create stories for coverage gaps; label by component |
+| **qa-flaky-detector** | Create stories for flaky tests; story type = bug |
+
+When qa-bug-ticket-creator or qa-task-creator outputs a structured ticket, this skill translates it to Shortcut story format and creates/updates via API.
+
+## Trigger Phrases
+
+- "Create Shortcut story from [bug report / test failure]"
+- "Add QA task to Shortcut"
+- "Create story in Shortcut for coverage gap"
+- "Update Shortcut story #123 with verification result"
+- "Search Shortcut for stories in epic [name]"
+- "Link story to test case / requirement"
+- "Bulk-create Shortcut stories from [coverage / spec / flaky] output"
+
+## Workflow
+
+1. **Input** — Bug report, QA task, coverage gap, or user request
+2. **Map** — Translate to Shortcut story format per `references/field-mapping.md`
+3. **Resolve** — Get project_id, epic_id, iteration_id from workspace (or user input)
+4. **Create/Update** — POST or PUT via REST API
+5. **Link** — Add external links to test cases, requirements, evidence
+6. **Output** — Return story URL and ID
+
+## Scope
+
+**Can do (autonomous):**
+- Create stories from bug reports and QA tasks
+- Update story status, labels, description
+- Search stories by query, epic, iteration
+- Map QA metadata to Shortcut labels and story types
+- Add external links to test cases and requirements
+- Work with qa-bug-ticket-creator and qa-task-creator outputs
+
+**Cannot do (requires confirmation):**
+- Create stories without project_id (user must provide or configure)
+- Assign to members without mapping
+- Create epics/iterations without workspace admin
+
+**Will not do (out of scope):**
+- Modify production or test code
+- Close or archive stories (stakeholder responsibility)
+- Integrate with Jira/Linear/GitHub (use respective skills)
+
+## Quality Checklist
+
+- [ ] Story includes title, description, and appropriate story type
+- [ ] Labels map to QA metadata (severity, component, test type)
+- [ ] External links added for test cases/requirements when applicable
+- [ ] No hardcoded secrets; token from `SHORTCUT_API_TOKEN`
+- [ ] Field mapping follows `references/field-mapping.md`
+- [ ] API patterns from `references/api-patterns.md` used correctly
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| 401 Unauthorized | Missing or invalid token | Check `SHORTCUT_API_TOKEN`; regenerate at Shortcut Settings |
+| 404 Not Found | Invalid story_id or project_id | Verify IDs; use search to resolve by name |
+| 422 Validation Error | Invalid field value | Check field-mapping; ensure enum values match Shortcut |
+| Rate limit (429) | >200 req/min | Throttle requests; batch where possible |
+| Epic/iteration not found | ID from wrong workspace | List epics/iterations; use correct IDs |
+| Labels not applied | Label doesn't exist | Create labels in Shortcut; use exact names |
+
+## Reference Files
+
+| Topic | File |
+| ----- | ---- |
+| API patterns (stories, epics, iterations) | `references/api-patterns.md` |
+| QA field → Shortcut field mapping | `references/field-mapping.md` |