qa-skills 3.0.0 → 3.1.0

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

@@ -1,170 +0,0 @@
-# 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

@@ -1,150 +0,0 @@
----
-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

@@ -1,175 +0,0 @@
-# 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`.