qualyx 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Koray Uysal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,523 @@
+# Qualyx
+
+[![npm version](https://img.shields.io/npm/v/qualyx.svg)](https://www.npmjs.com/package/qualyx)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/qualyx.svg)](https://nodejs.org)
+
+**AI-powered QA automation that understands your app like a human does.**
+
+Write tests in plain English. No selectors, no fragile locators, no maintenance headaches. Qualyx uses Claude AI to intelligently navigate and test your web applications.
+
+```yaml
+rules:
+  - id: checkout-flow
+    name: Complete purchase flow
+    steps:
+      - Add a product to the cart
+      - Go to checkout
+      - Fill in shipping details
+      - Complete the payment
+    validations:
+      - Order confirmation is displayed
+```
+
+---
+
+## Overview
+
+Qualyx allows you to define tests in natural language YAML, which are then executed by Claude Code CLI using Playwright for browser automation. This enables writing tests that are:
+
+- **Human-readable** - Tests are written in plain English
+- **Resilient** - AI adapts to UI changes without brittle selectors
+- **Comprehensive** - Complex user flows are easy to describe
+
+## Installation
+
+```bash
+npm install -g qualyx
+```
+
+**Requirements:**
+- Node.js 18+
+- Claude Code CLI (`npm install -g @anthropic-ai/claude-code`)
+
+## Quick Start
+
+1. **Initialize a configuration file:**
+
+```bash
+qualyx init
+```
+
+2. **Edit `qualyx.yml`** to configure your apps and tests
+
+3. **Validate your configuration:**
+
+```bash
+qualyx validate
+```
+
+4. **Run tests:**
+
+```bash
+qualyx run
+```
+
+## Configuration
+
+Tests are defined in `qualyx.yml`:
+
+```yaml
+organization:
+  name: My Company
+  defaults:
+    timeout: 30000
+    retries: 2
+
+apps:
+  - name: my-app
+    url: https://myapp.com
+    auth:
+      type: form-login
+      credentials:
+        email: ${TEST_USER_EMAIL}
+        password: ${TEST_USER_PASSWORD}
+
+    rules:
+      - id: user-login
+        name: User can login
+        severity: critical
+        steps:
+          - Navigate to login page
+          - Enter email and password
+          - Click login button
+          - Wait for dashboard to load
+        validations:
+          - User name is displayed in header
+          - Dashboard shows welcome message
+```
+
+### Configuration Options
+
+#### Organization
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `name` | Organization name | Required |
+| `defaults.timeout` | Default timeout (ms) | 30000 |
+| `defaults.retries` | Default retry count | 2 |
+
+#### Apps
+
+| Field | Description |
+|-------|-------------|
+| `name` | App identifier |
+| `url` | Base URL |
+| `environments` | Named URL mappings |
+| `auth` | Authentication config |
+| `screenshots` | Screenshot capture settings |
+| `setup` | Setup steps run once before rules |
+| `rules` | Test rules array |
+
+#### Rules
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique identifier |
+| `name` | Human-readable name |
+| `severity` | critical, high, medium, low |
+| `timeout` | Override default timeout |
+| `steps` | Test steps (strings or objects) |
+| `validations` | Expected outcomes |
+| `on_failure` | Actions on failure |
+| `test_data` | Dynamic test data |
+| `schedule` | Cron expression for scheduled runs |
+| `skip_setup` | Skip app setup for this rule |
+
+### Step Syntax
+
+Steps can be simple strings:
+
+```yaml
+steps:
+  - Navigate to the homepage
+  - Click the login button
+```
+
+Or objects with hints:
+
+```yaml
+steps:
+  - action: Fill payment form
+    hint: Use test card 4242424242424242
+    caution: Do NOT click submit
+```
+
+### Setup Blocks
+
+Setup steps run once per app before any rules execute:
+
+```yaml
+apps:
+  - name: my-app
+    url: https://myapp.com
+    setup:
+      - Login to the application
+      - Navigate to dashboard
+    rules:
+      - id: test-1
+        name: Test dashboard features
+        skip_setup: false  # Default: use setup
+        steps:
+          - Check dashboard widgets
+```
+
+### Screenshot Configuration
+
+Configure screenshot capture:
+
+```yaml
+apps:
+  - name: my-app
+    screenshots:
+      on_failure: true   # Capture on failure (default)
+      on_success: false  # Capture on success
+      each_step: false   # Capture after each step
+```
+
+### Scheduling
+
+Schedule tests with cron expressions:
+
+```yaml
+rules:
+  - id: health-check
+    name: Health Check
+    schedule: "*/30 * * * *"  # Every 30 minutes
+    steps:
+      - Verify homepage loads
+
+  - id: daily-smoke
+    name: Daily Smoke Test
+    schedule: "0 7 * * *"  # Daily at 7 AM
+```
+
+### Environment Variables
+
+Credentials use `${VAR_NAME}` syntax:
+
+```yaml
+credentials:
+  email: ${TEST_USER_EMAIL}
+  password: ${TEST_USER_PASSWORD}
+```
+
+Set these in your environment or CI/CD pipeline.
+
+## CLI Commands
+
+### `qualyx init`
+
+Create a starter configuration file.
+
+```bash
+qualyx init
+qualyx init --force  # Overwrite existing
+```
+
+### `qualyx validate`
+
+Validate configuration syntax.
+
+```bash
+qualyx validate
+qualyx validate --config path/to/config.yml
+qualyx validate --strict  # Warnings as errors
+```
+
+### `qualyx list`
+
+List configured apps and rules.
+
+```bash
+qualyx list           # Show all
+qualyx list apps      # Apps only
+qualyx list rules     # Rules only
+qualyx list --format json
+```
+
+### `qualyx run`
+
+Execute tests.
+
+```bash
+qualyx run                        # Run all tests
+qualyx run --app my-app           # Filter by app
+qualyx run --rule user-login      # Filter by rule
+qualyx run --environment staging  # Use staging URLs
+qualyx run --dry-run              # Preview without execution
+qualyx run --headed               # Show browser
+qualyx run --verbose              # Detailed output
+qualyx run --report               # Generate HTML report
+qualyx run --retries 3            # Override retry count
+qualyx run --timeout 60000        # Override timeout
+qualyx run --parallel             # Run tests in parallel
+qualyx run --max-parallel 5       # Limit concurrent tests
+qualyx run --collect-metrics      # Collect performance metrics
+```
+
+### `qualyx report`
+
+View or regenerate test reports.
+
+```bash
+qualyx report
+qualyx report --run-id abc123
+```
+
+### `qualyx history`
+
+View test run history.
+
+```bash
+qualyx history
+qualyx history --limit 20
+qualyx history --failed
+qualyx history --format json
+```
+
+### `qualyx schedule`
+
+Manage scheduled test rules.
+
+```bash
+qualyx schedule list              # List all scheduled rules
+qualyx schedule cron              # Generate crontab entries
+qualyx schedule cron --output crontab.txt
+qualyx schedule github            # Generate GitHub Actions workflow
+qualyx schedule github --output .github/workflows/qualyx.yml
+```
+
+## Integrations
+
+### Slack Notifications
+
+Send test results to Slack:
+
+```yaml
+notifications:
+  slack:
+    webhook_url: ${SLACK_WEBHOOK_URL}
+    on_failure: true
+    on_success: false
+    mention_on_failure:
+      - U123456789  # Slack user IDs
+```
+
+### Email Notifications
+
+Send test results via email:
+
+```yaml
+notifications:
+  email:
+    smtp_host: smtp.gmail.com
+    smtp_port: 587
+    smtp_secure: false
+    smtp_user: ${SMTP_USER}
+    smtp_pass: ${SMTP_PASS}
+    from: qa@company.com
+    to:
+      - team@company.com
+      - alerts@company.com
+    on_failure: true
+    on_success: false
+    subject_prefix: "[Qualyx]"
+```
+
+Features:
+- HTML and plain text email formats
+- Configurable triggers (on_failure, on_success)
+- Customizable subject prefix
+- Link to HTML report (if generated)
+
+### Microsoft Teams Notifications
+
+Send test results to Microsoft Teams:
+
+```yaml
+notifications:
+  teams:
+    webhook_url: ${TEAMS_WEBHOOK_URL}
+    on_failure: true
+    on_success: false
+    mention_on_failure:
+      - user@company.com
+```
+
+Features:
+- Rich Adaptive Card messages
+- User mentions on failure
+- Summary with pass/fail counts
+- Link to HTML report
+
+### Jira Integration
+
+Automatically create issues for failed tests:
+
+```yaml
+integrations:
+  jira:
+    base_url: https://company.atlassian.net
+    email: ${JIRA_EMAIL}
+    api_token: ${JIRA_API_TOKEN}
+    project_key: QA
+    create_issues: true
+    issue_type: Bug
+    labels:
+      - qualyx
+      - automated-test
+```
+
+Features:
+- Creates issues on test failures
+- Prevents duplicate issues (checks for existing open issues)
+- Adds comments to existing issues on re-failure
+
+## Parallel Execution
+
+Run tests in parallel to speed up test suites:
+
+```bash
+qualyx run --parallel              # Run tests in parallel (default: 3 concurrent)
+qualyx run --parallel --max-parallel 5  # Limit to 5 concurrent tests
+```
+
+Notes:
+- Setup blocks run sequentially before parallel test execution
+- Results are ordered in original test order
+- Useful for independent tests that don't share state
+
+## Performance Metrics
+
+Collect performance metrics during test execution:
+
+```bash
+qualyx run --collect-metrics
+```
+
+Metrics collected:
+- **Page Load Time** - Time from navigation start to load event
+- **DOM Content Loaded** - Time until DOM is fully parsed
+- **First Contentful Paint (FCP)** - Time until first content renders
+- **Largest Contentful Paint (LCP)** - Time until largest content element renders
+- **Total Request Count** - Number of network requests
+- **Total Transfer Size** - Total bytes transferred
+
+## Output
+
+### Console Output
+
+```
+  Qualyx Test Runner
+  Running 4 tests...
+
+  ✓ flight-booking / Search for flights  CRITICAL  (2.3s)
+  ✓ flight-booking / Filter by price     HIGH      (1.8s)
+  ✗ flight-booking / Complete booking    CRITICAL  (5.2s)
+    Error: Payment form did not appear
+  ✓ hotel-booking / Search for hotels    CRITICAL  (2.1s)
+
+  Summary
+  ────────────────────────────────────────
+  Total:   4
+  Passed:  3
+  Failed:  1
+  Duration: 11.4s
+  Pass Rate: 75.0%
+
+  ✗ 1 test failed
+```
+
+### HTML Reports
+
+Generate visual reports with `--report`:
+
+```bash
+qualyx run --report
+```
+
+Reports are saved to `./qualyx-reports/`.
+
+## GitHub Actions Integration
+
+```yaml
+name: QA Tests
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '0 */6 * * *'  # Every 6 hours
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        run: |
+          npm install -g qualyx @anthropic-ai/claude-code
+
+      - name: Run QA tests
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
+          TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
+        run: qualyx run --report
+
+      - name: Upload report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: qa-report
+          path: qualyx-reports/
+```
+
+## Cost Considerations
+
+Each test execution uses Claude API calls. To manage costs:
+
+1. Use `--dry-run` to preview tests
+2. Run critical tests more frequently
+3. Run full suite less frequently (e.g., nightly)
+4. Group related assertions in single rules
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/korayuysal/qualyx.git
+cd qualyx
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev -- run --dry-run
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+## License
+
+MIT

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,6 @@
+export interface InitOptions {
+    force?: boolean;
+    path?: string;
+}
+export declare function runInit(options?: InitOptions): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAuGA,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBtE"}

package/dist/cli/commands/init.js

@@ -0,0 +1,124 @@
+import { writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+const STARTER_CONFIG = `# Qualyx Configuration
+# Documentation: https://github.com/korayuysal/qualyx
+
+organization:
+  name: My Organization
+  defaults:
+    timeout: 30000
+    retries: 2
+
+apps:
+  - name: my-app
+    url: https://example.com
+    environments:
+      production: https://example.com
+      staging: https://staging.example.com
+
+    # Optional authentication configuration
+    # auth:
+    #   type: form-login
+    #   credentials:
+    #     email: \${TEST_USER_EMAIL}
+    #     password: \${TEST_USER_PASSWORD}
+
+    # Optional screenshot settings
+    # screenshots:
+    #   on_failure: true
+    #   on_success: false
+    #   each_step: false
+
+    # Optional setup steps (run once per app before rules)
+    # setup:
+    #   - Login to the application
+    #   - Navigate to dashboard
+
+    rules:
+      - id: homepage-loads
+        name: Homepage loads successfully
+        severity: critical
+        steps:
+          - Navigate to the homepage
+          - Verify the page loads without errors
+        validations:
+          - Page title is visible
+          - No console errors appear
+
+      - id: navigation-works
+        name: Main navigation is functional
+        severity: high
+        # Optional: schedule this test to run automatically
+        # schedule: "0 7 * * *"  # Daily at 7 AM (cron syntax)
+        steps:
+          - Navigate to the homepage
+          - Click on the main navigation menu
+          - Verify navigation links are visible
+        validations:
+          - Navigation menu is displayed
+          - Links are clickable
+
+      # Example of a more complex test with hints
+      # - id: user-login
+      #   name: User can log in
+      #   severity: critical
+      #   schedule: "*/30 * * * *"  # Every 30 minutes
+      #   skip_setup: false  # Set to true to skip app setup for this rule
+      #   steps:
+      #     - Navigate to the login page
+      #     - action: Enter email address
+      #       hint: Use the email field, typically an input with type="email"
+      #     - action: Enter password
+      #       hint: Use the password field
+      #     - Click the login button
+      #     - Wait for redirect to dashboard
+      #   validations:
+      #     - User is redirected to dashboard
+      #     - User name is displayed in header
+
+# Optional: Slack notifications
+# notifications:
+#   slack:
+#     webhook_url: \${SLACK_WEBHOOK_URL}
+#     on_failure: true
+#     on_success: false
+#     mention_on_failure:
+#       - U123456789  # Slack user IDs to mention on failure
+
+# Optional: Jira integration for automatic issue creation
+# integrations:
+#   jira:
+#     base_url: https://company.atlassian.net
+#     email: \${JIRA_EMAIL}
+#     api_token: \${JIRA_API_TOKEN}
+#     project_key: QA
+#     create_issues: true
+#     issue_type: Bug
+#     labels:
+#       - qualyx
+#       - automated-test
+`;
+export async function runInit(options = {}) {
+    const configPath = resolve(options.path || 'qualyx.yml');
+    // Check if file already exists
+    if (existsSync(configPath) && !options.force) {
+        console.log();
+        console.log(chalk.yellow(`  Configuration file already exists: ${configPath}`));
+        console.log(chalk.gray('  Use --force to overwrite'));
+        console.log();
+        process.exit(1);
+    }
+    // Write the starter configuration
+    writeFileSync(configPath, STARTER_CONFIG, 'utf-8');
+    console.log();
+    console.log(chalk.green(`  ✓ Created configuration file: ${configPath}`));
+    console.log();
+    console.log(chalk.gray('  Next steps:'));
+    console.log(chalk.gray('    1. Edit qualyx.yml to configure your apps and tests'));
+    console.log(chalk.gray('    2. Set environment variables for credentials'));
+    console.log(chalk.gray('    3. Run `qualyx validate` to check your configuration'));
+    console.log(chalk.gray('    4. Run `qualyx run` to execute tests'));
+    console.log();
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiGtB,CAAC;AAOF,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,UAAuB,EAAE;IACrD,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,IAAI,YAAY,CAAC,CAAC;IAEzD,+BAA+B;IAC/B,IAAI,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QAC7C,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,wCAAwC,UAAU,EAAE,CAAC,CAAC,CAAC;QAChF,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,kCAAkC;IAClC,aAAa,CAAC,UAAU,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC;IAEnD,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,mCAAmC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC1E,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;IACzC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC,CAAC;IACnF,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC,CAAC;IAC5E,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC,CAAC;IACpF,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC"}

package/dist/cli/commands/list.d.ts

@@ -0,0 +1,3 @@
+import type { ListOptions } from '../../types/index.js';
+export declare function runList(resource: 'apps' | 'rules' | undefined, configPath?: string, options?: ListOptions): Promise<void>;
+//# sourceMappingURL=list.d.ts.map

package/dist/cli/commands/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/list.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACtC,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CA8Ef"}