qa-skills 3.0.0

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

@@ -0,0 +1,170 @@
+# Selenium Java Patterns
+
+## Page Object Model (POM)
+
+### Base Page
+
+```java
+public abstract class BasePage {
+    protected WebDriver driver;
+    protected WebDriverWait wait;
+
+    public BasePage(WebDriver driver) {
+        this.driver = driver;
+        this.wait = new WebDriverWait(driver, Duration.ofSeconds(10));
+        PageFactory.initElements(driver, this);
+    }
+}
+```
+
+### Page with PageFactory
+
+```java
+public class LoginPage extends BasePage {
+    @FindBy(id = "username")
+    private WebElement usernameInput;
+
+    @FindBy(id = "password")
+    private WebElement passwordInput;
+
+    @FindBy(css = "button[type='submit']")
+    private WebElement submitButton;
+
+    public LoginPage(WebDriver driver) {
+        super(driver);
+    }
+
+    public void login(String user, String pass) {
+        usernameInput.sendKeys(user);
+        passwordInput.sendKeys(pass);
+        submitButton.click();
+    }
+}
+```
+
+### Lazy Locators (FindBy with custom locator)
+
+```java
+@FindBy(css = "div.user[data-id='%s']")
+private String userItemTemplate;
+
+public WebElement getUserItem(String id) {
+    return driver.findElement(By.cssSelector(String.format(userItemTemplate, id)));
+}
+```
+
+## Explicit Waits
+
+### WebDriverWait + ExpectedConditions
+
+```java
+// Visibility
+WebElement el = wait.until(ExpectedConditions.visibilityOfElementLocated(By.id("result")));
+
+// Clickable
+WebElement btn = wait.until(ExpectedConditions.elementToBeClickable(By.cssSelector(".submit")));
+
+// Presence (in DOM, may not be visible)
+WebElement el = wait.until(ExpectedConditions.presenceOfElementLocated(By.id("dynamic")));
+
+// Text present
+wait.until(ExpectedConditions.textToBePresentInElementLocated(By.id("status"), "Success"));
+
+// URL contains
+wait.until(ExpectedConditions.urlContains("/dashboard"));
+
+// Custom condition
+wait.until(d -> ((JavascriptExecutor) d).executeScript("return document.readyState").equals("complete"));
+```
+
+### Timeout Configuration
+
+```java
+WebDriverWait shortWait = new WebDriverWait(driver, Duration.ofSeconds(5));
+WebDriverWait longWait = new WebDriverWait(driver, Duration.ofSeconds(30));
+```
+
+## Selectors (By strategies)
+
+| Strategy | Example |
+| -------- | ------- |
+| By.id | `By.id("submit-btn")` |
+| By.cssSelector | `By.cssSelector("button.primary")` |
+| By.xpath | `By.xpath("//button[text()='Submit']")` |
+| By.name | `By.name("email")` |
+| By.className | `By.className("btn-primary")` |
+| By.linkText | `By.linkText("Sign in")` |
+| By.partialLinkText | `By.partialLinkText("Sign")` |
+| By.tagName | `By.tagName("input")` |
+
+Prefer: ID > data attributes > CSS > XPath.
+
+## Actions
+
+### Basic Interactions
+
+```java
+element.click();
+element.sendKeys("text");
+element.clear();
+element.getText();
+element.getAttribute("href");
+element.isDisplayed();
+element.isEnabled();
+element.isSelected();
+```
+
+### Actions API (complex interactions)
+
+```java
+Actions actions = new Actions(driver);
+actions.moveToElement(element).click().perform();
+actions.dragAndDrop(source, target).perform();
+actions.keyDown(Keys.CONTROL).sendKeys("a").keyUp(Keys.CONTROL).perform();
+actions.sendKeys(element, Keys.ENTER).perform();
+```
+
+### Select (dropdowns)
+
+```java
+Select select = new Select(driver.findElement(By.id("country")));
+select.selectByValue("US");
+select.selectByVisibleText("United States");
+select.selectByIndex(0);
+```
+
+## Alerts
+
+```java
+Alert alert = wait.until(ExpectedConditions.alertIsPresent());
+String text = alert.getText();
+alert.accept();  // OK
+alert.dismiss(); // Cancel
+alert.sendKeys("input");  // For prompt
+```
+
+## Frames and Windows
+
+```java
+// Switch to frame
+driver.switchTo().frame("frameName");
+driver.switchTo().frame(0);
+driver.switchTo().frame(frameElement);
+driver.switchTo().defaultContent();
+
+// New window/tab
+String mainHandle = driver.getWindowHandle();
+for (String handle : driver.getWindowHandles()) {
+    if (!handle.equals(mainHandle)) {
+        driver.switchTo().window(handle);
+        break;
+    }
+}
+```
+
+## File Upload
+
+```java
+WebElement fileInput = driver.findElement(By.cssSelector("input[type='file']"));
+fileInput.sendKeys(Paths.get("/path/to/file.txt").toAbsolutePath().toString());
+```

package/skills/qa-selenium-py-writer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: qa-selenium-py-writer
+description: Generate Selenium E2E tests for Python with WebDriver, explicit/implicit waits, Page Object Model, and headless browser support.
+output_dir: tests/e2e
+---
+
+# QA Selenium Python Writer
+
+## Purpose
+
+Write Selenium Python E2E tests from test case specifications. Transform structured test cases (from qa-testcase-from-docs, qa-manual-test-designer, qa-browser-data-collector, or specs) into executable Selenium test files with WebDriver, explicit waits, Page Object Model, and headless browser support.
+
+## Trigger Phrases
+
+- "Write Selenium tests for [feature/flow]"
+- "Generate Selenium E2E tests from test cases"
+- "Create Selenium Python tests with POM"
+- "Add Selenium tests for [URL/page]"
+- "Selenium tests with WebDriver for [browser]"
+- "Selenium Python Page Object Model tests"
+- "Headless Selenium tests for [feature]"
+- "Selenium tests with explicit waits"
+- "Heal my failing Selenium tests"
+
+## Key Features
+
+| Feature | Description |
+| ------- | ----------- |
+| **WebDriver** | Chrome, Firefox, Edge, Safari via Selenium WebDriver |
+| **Explicit waits** | WebDriverWait + expected_conditions; avoid implicit waits |
+| **Implicit waits** | Fallback only; prefer explicit waits |
+| **Page Object Model** | POM with @property for locators; base page + page-specific classes |
+| **Headless mode** | Chrome/Firefox headless for CI and faster runs |
+| **ActionChains** | Complex interactions: drag-drop, hover, key combos |
+| **Select** | Dropdown handling via Select class |
+| **pytest integration** | Fixtures for driver setup/teardown, conftest.py |
+
+## Workflow
+
+1. **Read test cases** — From specs, requirements, manual test designs, or browser-collected data
+2. **Analyze app** — Inspect pages, forms, flows; identify locators and interactions
+3. **Generate tests with POM** — Produce `test_{feature}.py` with Page Objects
+4. **Configure WebDriver** — Set up driver fixtures, headless options, timeouts
+5. **Run** — User runs `pytest` to execute tests
+
+## Context7 MCP
+
+Use **Context7 MCP** for Selenium Python documentation when:
+- WebDriver API or expected_conditions syntax is uncertain
+- ActionChains, Select, or alert handling needs verification
+- Browser-specific options (Chrome, Firefox headless) require up-to-date reference
+
+## Key Patterns
+
+| Pattern | Usage |
+| ------- | ----- |
+| `driver.get(url)` | Navigate to URL |
+| `driver.find_element(By.ID, "id")` | Find by ID |
+| `driver.find_element(By.CSS_SELECTOR, "selector")` | Find by CSS |
+| `driver.find_element(By.XPATH, "xpath")` | Find by XPath |
+| `driver.find_element(By.NAME, "name")` | Find by name |
+| `driver.find_element(By.CLASS_NAME, "class")` | Find by class |
+| `WebDriverWait(driver, timeout).until(EC.visibility_of_element_located(...))` | Explicit wait |
+| POM with `@property` | Encapsulate locators in page classes |
+| `ActionChains(driver)` | Drag, hover, key combos |
+| `Select(element)` | Dropdown select by value/text/index |
+
+## Wait Strategies
+
+Prefer explicit waits; avoid implicit waits for reliability:
+
+```python
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.common.by import By
+
+wait = WebDriverWait(driver, 10)
+element = wait.until(EC.visibility_of_element_located((By.ID, "submit-btn")))
+element.click()
+```
+
+Common expected conditions: `visibility_of_element_located`, `element_to_be_clickable`, `presence_of_element_located`, `text_to_be_present_in_element`, `url_contains`.
+
+## pytest Integration
+
+- **Fixtures** — `driver` fixture for setup/teardown; scope function or class
+- **conftest.py** — Shared driver factory, base URL, browser options
+- **File naming** — `test_{feature}.py` (e.g., `test_login.py`, `test_checkout.py`)
+
+See `references/config.md` for pytest + Selenium setup.
+
+## File Naming
+
+- `test_{feature}.py` — Preferred (e.g., `test_login.py`, `test_search.py`)
+- Page objects: `pages/{page_name}_page.py` or `page_objects/{name}.py`
+- Place in `tests/` per project convention
+
+## Scope
+
+**Can do (autonomous):**
+- Generate Selenium Python E2E tests from test case specs
+- Apply Page Object Model with @property locators
+- Use explicit waits (WebDriverWait + expected_conditions)
+- Configure WebDriver (Chrome, Firefox, Edge, headless)
+- Use ActionChains for complex interactions; Select for dropdowns
+- Integrate with pytest via fixtures and conftest.py
+- Use Context7 MCP for Selenium Python docs
+- Delegate to qa-test-healer when tests fail (Heal Mode)
+
+**Cannot do (requires confirmation):**
+- Change production code structure
+- Add dependencies not in requirements.txt
+- Override project Selenium/pytest config without approval
+- Navigate to URLs not provided
+
+**Will not do (out of scope):**
+- Execute tests (user runs `pytest`)
+- Write Playwright/Cypress tests (use qa-playwright-ts-writer, qa-cypress-writer)
+- Modify CI/CD pipelines
+- Bypass security or access restricted areas
+
+## References
+
+- `references/patterns.md` — Locators, waits, POM, ActionChains, Select, file upload, alerts, frames, windows
+- `references/config.md` — WebDriver manager, pytest integration, headless config
+- `references/best-practices.md` — Explicit waits, POM, stable locators, driver management
+
+## Quality Checklist
+
+- [ ] Explicit waits used; avoid implicit waits where possible
+- [ ] No hardcoded sleeps; prefer WebDriverWait + expected_conditions
+- [ ] POM pattern applied for page-specific logic
+- [ ] Stable locators (ID, data attributes, CSS; XPath as fallback)
+- [ ] Tests independent (no shared state, order-independent)
+- [ ] Proper teardown (driver.quit in fixture)
+- [ ] Traceability to test case IDs where applicable
+- [ ] No hardcoded secrets (use env vars)
+- [ ] File naming follows `test_{feature}.py` convention
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| Element not found | Selector too specific, timing | Use explicit wait; prefer ID/CSS over fragile XPath |
+| StaleElementReferenceException | DOM changed after find | Re-find element before interaction; use explicit wait |
+| Timeout | Element not ready, slow page | Increase WebDriverWait timeout; check for overlays/modals |
+| Flaky tests | Implicit wait, race conditions | Replace implicit with explicit waits; ensure test isolation |
+| Driver not found | WebDriver binary missing | Use webdriver-manager; ensure browser installed |
+| Headless fails | Browser options incorrect | Verify Chrome/Firefox headless options for your Selenium version |
+| Select fails | Not a select element | Use Select only on `<select>` elements; check element type |

package/skills/qa-selenium-py-writer/references/best-practices.md

@@ -0,0 +1,175 @@
+# Selenium Python Best Practices
+
+Guidelines for maintainable, reliable Selenium E2E tests.
+
+## Explicit Waits (Never Implicit)
+
+**Always use explicit waits** for element availability. Implicit waits apply globally and can cause unpredictable behavior when combined with explicit waits.
+
+```python
+# Good
+element = WebDriverWait(driver, 10).until(
+    EC.visibility_of_element_located((By.ID, "submit"))
+)
+element.click()
+
+# Bad
+driver.implicitly_wait(10)  # Avoid; masks timing issues
+driver.find_element(By.ID, "submit").click()
+```
+
+**Exception:** A single short implicit wait (e.g., 2–5 seconds) at driver init can reduce boilerplate for stable pages, but explicit waits are still preferred for critical interactions.
+
+## Page Object Model (POM)
+
+Encapsulate page structure and actions in dedicated classes:
+
+```python
+# pages/base.py
+class BasePage:
+    def __init__(self, driver, base_url):
+        self.driver = driver
+        self.base_url = base_url
+
+    def open(self, path=""):
+        self.driver.get(f"{self.base_url}{path}")
+
+    def find(self, by, value):
+        return WebDriverWait(self.driver, 10).until(
+            EC.visibility_of_element_located((by, value))
+        )
+
+
+# pages/login.py
+class LoginPage(BasePage):
+    @property
+    def username(self):
+        return self.find(By.ID, "username")
+
+    @property
+    def password(self):
+        return self.find(By.ID, "password")
+
+    def login(self, user, pwd):
+        self.username.send_keys(user)
+        self.password.send_keys(pwd)
+        self.find(By.CSS_SELECTOR, "button[type='submit']").click()
+```
+
+Benefits: reuse, easier maintenance, clearer tests.
+
+## Stable Locators
+
+Prefer locators that are less likely to break when the UI changes:
+
+| Priority | Locator | Stability |
+| -------- | ------- | --------- |
+| 1 | By.ID | High (if IDs are stable) |
+| 2 | By.NAME | High for form fields |
+| 3 | data-testid | High (add to markup for tests) |
+| 4 | By.CSS_SELECTOR (semantic) | Medium |
+| 5 | By.XPATH (text) | Low (breaks with i18n) |
+| 6 | By.CLASS_NAME | Low (styling changes) |
+
+```python
+# Prefer
+driver.find_element(By.ID, "login-form")
+driver.find_element(By.CSS_SELECTOR, "[data-testid='submit-btn']")
+
+# Avoid when possible
+driver.find_element(By.XPATH, "//div[@class='btn-primary']/span")
+driver.find_element(By.CLASS_NAME, "btn-primary")  # Styling may change
+```
+
+## Driver Management
+
+- **One driver per test** — Use function-scoped fixtures to avoid shared state.
+- **Always quit** — Use `yield` in fixtures to ensure `driver.quit()` runs.
+- **Avoid global driver** — Prefer dependency injection via fixtures.
+
+```python
+@pytest.fixture(scope="function")
+def driver():
+    driver = webdriver.Chrome(options=options)
+    try:
+        yield driver
+    finally:
+        driver.quit()
+```
+
+## Test Isolation
+
+- Each test should be independent.
+- Do not rely on test execution order.
+- Reset application state when needed (e.g., logout, clear data).
+- Use fresh driver instances per test.
+
+## Avoid Sleep
+
+Replace `time.sleep()` with explicit waits:
+
+```python
+# Bad
+time.sleep(5)
+element.click()
+
+# Good
+WebDriverWait(driver, 10).until(
+    EC.element_to_be_clickable((By.ID, "submit"))
+).click()
+```
+
+## ActionChains for Complex Interactions
+
+Use ActionChains for hover, drag-and-drop, and modifier keys:
+
+```python
+from selenium.webdriver.common.action_chains import ActionChains
+
+actions = ActionChains(driver)
+actions.move_to_element(menu).click(submenu).perform()
+```
+
+## Select for Dropdowns
+
+Use the `Select` class instead of raw clicks for `<select>` elements:
+
+```python
+from selenium.webdriver.support.ui import Select
+
+select = Select(driver.find_element(By.ID, "country"))
+select.select_by_visible_text("United States")
+```
+
+## Screenshots on Failure
+
+```python
+# conftest.py
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    report = outcome.get_result()
+    if report.when == "call" and report.failed:
+        driver = item.funcargs.get("driver", None)
+        if driver:
+            driver.save_screenshot(f"failure_{item.name}.png")
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+| ------------ | --------------- |
+| Implicit wait as primary strategy | Explicit WebDriverWait + EC |
+| `time.sleep()` for synchronization | WebDriverWait with expected conditions |
+| Raw XPATH with long chains | ID, data-testid, or shorter CSS |
+| Shared mutable driver across tests | Function-scoped fixture |
+| Hardcoded credentials | Env vars, fixtures, or test config |
+| Asserting implementation details | Assert user-visible outcomes |
+| One giant test | Split into focused scenarios |
+
+## CI/CD Considerations
+
+- Use headless mode: `--headless=new` (Chrome).
+- Add `--no-sandbox` and `--disable-dev-shm-usage` for Docker/CI.
+- Use webdriver-manager or pre-installed drivers.
+- Consider retries for flaky tests: `pytest --reruns 2`.