@bugzy-ai/bugzy 1.2.0

package/templates/init/CLAUDE.md

@@ -0,0 +1,157 @@
+# Project Memory
+
+## Project Overview
+**Type**: Test Management System
+**Purpose**: Autonomous QA testing with AI-based test generation and execution
+
+## SECURITY NOTICE
+
+**CRITICAL: Never Read the .env File**
+
+All agents, subagents, and slash commands must follow this security policy:
+
+- **NEVER read the `.env` file** - It contains secrets, credentials, and sensitive data
+- **ALWAYS use `.env.testdata`** instead - It contains only variable names, never actual values
+- **Reference variables by name only** - e.g., TEST_BASE_URL, TEST_USER_EMAIL (never read the actual values)
+- **This is enforced** - `.claude/settings.json` has `Read(.env)` in the deny list
+
+When you need to know what environment variables are available:
+1. Read `.env.testdata` to see variable names and structure
+2. Reference variables by name in documentation and instructions
+3. Trust that users will configure their own `.env` file from the example
+4. Never attempt to access actual credential values
+
+This policy applies to all agents, commands, and any code execution.
+
+## Agent System
+
+### Active Agents
+<!-- AUTO-GENERATED: This section is populated during project creation -->
+<!-- Configured agents will be listed here based on project setup -->
+
+Agents configured for this project are stored in `.claude/agents/`. These are specialized sub-agents that handle specific domains. The active agents and their integrations will be configured during project setup.
+
+### Agent Memory Index
+<!-- AUTO-GENERATED: Agent memory files are created during project setup -->
+
+Specialized memory files for domain experts will be created in `.bugzy/runtime/memory/` based on configured agents.
+
+## Project Structure
+
+### Core Components
+- **Test Plan**: `test-plan.md` - Generated via `/generate-test-plan` command using template
+- **Test Cases**: `./test-cases/` - Individual test case files generated via `/generate-test-cases`
+- **Exploration Reports**: `./exploration-reports/` - Structured reports from application exploration sessions
+- **Knowledge Base**: `.bugzy/runtime/knowledge-base.md` - Curated knowledge about the project (maintained using `.bugzy/runtime/knowledge-maintenance-guide.md`)
+- **Issue Tracking**: Managed by issue-tracker agent in your configured project management system
+- **Runtime**: `.bugzy/runtime/` - Project-specific runtime files:
+  - `memory/` - Agent memory and knowledge base files
+  - `templates/` - Document templates for test plan generation
+  - `knowledge-base.md` - Accumulated insights
+  - `project-context.md` - **CRITICAL**: Project SDLC, team information, QA workflow, and testing guidelines
+- **MCP Configuration**: `.bugzy/.mcp.json` - Template with all available MCP server configurations
+
+### Available Commands
+1. `/generate-test-plan` - Generate comprehensive test plan from product documentation using the documentation-researcher agent
+2. `/explore-application` - Systematically explore the application to discover UI elements, workflows, and behaviors, updating test plan with findings
+3. `/generate-test-cases` - Create E2E browser test cases (exploratory, functional, regression, smoke) based on documentation and test plan
+4. `/run-tests` - Execute test cases using the test-runner agent
+5. `/handle-message` - Process team responses and manage ongoing conversations with the product team using the team-communicator agent
+
+### Git Workflow
+
+**Git operations are now handled automatically by the execution environment.**
+
+Agents and commands should NOT perform git operations (commit, push). Instead:
+
+1. **Focus on core work**: Agents generate files and execute tests
+2. **External service handles git**: After task completion, the Cloud Run environment:
+   - Commits all changes with standardized messages
+   - Pushes to the remote repository
+   - Handles authentication and errors
+
+**Files Automatically Committed**:
+- `test-plan.md` - Test planning documents
+- `.env.testdata` - Environment variable templates
+- `./test-cases/*.md` - Individual test case files
+- `./exploration-reports/*.md` - Application exploration findings
+- `.bugzy/runtime/knowledge-base.md` - Accumulated testing insights
+- `.bugzy/runtime/memory/*.md` - Agent memory and knowledge base
+- `CLAUDE.md` - Updated project context (when modified)
+- `.bugzy/runtime/project-context.md` - Project-specific runtime context
+
+**Git-Ignored Files** (NOT committed):
+- `.env` - Local environment variables with secrets
+- `logs/` - Temporary log files
+- `tmp/` - Temporary files
+- `.playwright-mcp/` - Playwright videos (uploaded to GCS separately)
+- `node_modules/` - Node.js dependencies
+
+### Workflow
+
+#### Testing Workflow
+1. Generate test plan: `/generate-test-plan` command leverages the documentation-researcher agent to gather requirements
+2. Explore application: `/explore-application --focus [area] --depth [shallow|deep]` discovers actual UI elements and behaviors
+3. Create test cases: `/generate-test-cases --type [type] --focus [feature]` uses discovered documentation and exploration findings
+4. Execute tests: `/run-tests [test-id|type|tag|all]` runs test cases via test-runner agent
+5. Continuous refinement through exploration and test execution
+
+### Testing Lifecycle Phases
+1. **Initial Test Plan Creation** - From product documentation
+2. **Application Exploration** - Systematic discovery via `/explore-application`
+3. **Test Case Generation** - Stored as individual files with actual UI elements
+4. **Test Execution** - Automated runs via `/run-tests`
+5. **Continuous Refinement** - Through exploration and test execution
+6. **Regression Testing** - Scheduled or triggered execution
+
+## Key Project Insights
+<!-- Critical discoveries and patterns that apply across all domains -->
+
+## Cross-Domain Knowledge
+
+### Project Context Usage
+The `.bugzy/runtime/project-context.md` file contains critical project information that MUST be referenced by:
+- All agents during initialization to understand project specifics
+- All commands before processing to align with project requirements
+- Any custom implementations to maintain consistency
+
+Key information includes: QA workflow, story status management, bug reporting guidelines, testing environment details, and SDLC methodology.
+
+### Test Execution Standards
+
+**Automated Test Execution** (via `/run-tests` command):
+- Test runs are stored in hierarchical structure: `./test-runs/YYYYMMDD-HHMMSS/TC-XXX/exec-N/`
+- Each test run session creates:
+  - `execution-id.txt`: Contains BUGZY_EXECUTION_ID for session tracking
+  - `manifest.json`: Overall run metadata with all test cases and executions
+  - Per test case folders (`TC-001-login/`, etc.) containing execution attempts
+- Each execution attempt (`exec-1/`, `exec-2/`, `exec-3/`) contains:
+  - `result.json`: Playwright test result format with status, duration, errors, attachments
+  - `steps.json`: Step-by-step execution with video timestamps (if test uses `test.step()`)
+  - `video.webm`: Video recording (copied from Playwright's temp location)
+  - `trace.zip`: Trace file (only for failures)
+  - `screenshots/`: Screenshots directory (only for failures)
+- Videos are recorded for ALL tests, traces/screenshots only for failures
+- Custom Bugzy reporter handles all artifact organization automatically
+- External service uploads videos from execution folders to GCS
+
+**Step-Level Tracking** (Automated Tests):
+- Tests using `test.step()` API generate steps.json files with video timestamps
+- Each step includes timestamp and videoTimeSeconds for easy video navigation
+- High-level steps recommended (3-7 per test) for manageable navigation
+- Steps appear in both result.json (Playwright format) and steps.json (user-friendly format)
+- Tests without `test.step()` still work but won't have steps.json
+
+**Manual Test Execution** (via test-runner agent):
+- Manual test cases use separate format: `./test-runs/YYYYMMDD-HHMMSS/TC-XXX/`
+- Each test run generates:
+  - `summary.json`: Structured test result with video filename reference
+  - `steps.json`: Step-by-step execution with timestamps and video synchronization
+- Video recording via Playwright MCP --save-video flag
+- Videos remain in `.playwright-mcp/` folder - external service uploads to GCS
+
+**General Rules**:
+- NO test-related files should be created in project root
+- DO NOT copy, move, or delete video files manually
+- DO NOT CREATE ANY SUMMARY, REPORT, OR ADDITIONAL FILES unless explicitly requested
+<!-- Additional cross-domain information below -->

package/templates/init/test-runs/README.md

@@ -0,0 +1,45 @@
+# Test Runs
+
+This directory contains execution results and artifacts from test runs.
+
+## Structure
+
+Test runs are organized by timestamp and test case:
+```
+YYYYMMDD-HHMMSS/
+├── TC-XXX/
+│   ├── summary.json
+│   ├── steps.json
+│   └── video.webm
+```
+
+## Contents
+
+Each test run includes:
+- **summary.json**: Structured test result with video metadata and status
+- **steps.json**: Detailed execution steps with timestamps and video synchronization
+- **video.webm**: Video recording of the entire test execution
+
+**Note**: All test information (status, failures, step details, observations) is captured in the structured JSON files. The video provides visual evidence synchronized with the steps.
+
+## Test Result Schema
+
+All test results follow the schema defined in `.bugzy/runtime/templates/test-result-schema.md`.
+
+Key features:
+- Video recording with synchronized step navigation
+- Timestamped steps for precise playback control
+- Structured metadata for test status, type, and priority
+- User-friendly action descriptions for easy understanding
+
+## Usage
+
+Test runs are automatically generated when:
+- Tests are executed via automation
+- Manual test execution is logged
+- Event processing triggers test validation
+
+Results are used for:
+- Issue tracking via the issue-tracker agent
+- Learning extraction for continuous improvement
+- Regression analysis and pattern recognition

package/templates/playwright/BasePage.template.ts

@@ -0,0 +1,190 @@
+import { type Page, type Locator } from '@playwright/test';
+
+/**
+ * Base Page Object Model
+ * All page objects should extend this class
+ *
+ * Provides common functionality and patterns for page interactions
+ */
+export class BasePage {
+  readonly page: Page;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  /**
+   * Navigate to a specific path
+   * @param path - The path to navigate to (relative to baseURL)
+   */
+  async navigate(path: string): Promise<void> {
+    await this.page.goto(path);
+  }
+
+  /**
+   * Wait for the page to be fully loaded
+   */
+  async waitForPageLoad(): Promise<void> {
+    await this.page.waitForLoadState('networkidle');
+  }
+
+  /**
+   * Get the current URL
+   */
+  getCurrentURL(): string {
+    return this.page.url();
+  }
+
+  /**
+   * Get the page title
+   */
+  async getTitle(): Promise<string> {
+    return await this.page.title();
+  }
+
+  /**
+   * Wait for a locator to be visible
+   * @param locator - The locator to wait for
+   * @param timeout - Optional custom timeout
+   */
+  async waitForVisible(locator: Locator, timeout?: number): Promise<void> {
+    await locator.waitFor({ state: 'visible', timeout });
+  }
+
+  /**
+   * Wait for a locator to be hidden
+   * @param locator - The locator to wait for
+   * @param timeout - Optional custom timeout
+   */
+  async waitForHidden(locator: Locator, timeout?: number): Promise<void> {
+    await locator.waitFor({ state: 'hidden', timeout });
+  }
+
+  /**
+   * Click an element and wait for navigation
+   * @param locator - The element to click
+   */
+  async clickAndNavigate(locator: Locator): Promise<void> {
+    await Promise.all([
+      this.page.waitForNavigation(),
+      locator.click()
+    ]);
+  }
+
+  /**
+   * Fill a form field
+   * @param locator - The input field
+   * @param value - The value to fill
+   */
+  async fillField(locator: Locator, value: string): Promise<void> {
+    await locator.clear();
+    await locator.fill(value);
+  }
+
+  /**
+   * Select an option from a dropdown
+   * @param locator - The select element
+   * @param value - The value to select
+   */
+  async selectOption(locator: Locator, value: string): Promise<void> {
+    await locator.selectOption(value);
+  }
+
+  /**
+   * Check a checkbox
+   * @param locator - The checkbox element
+   */
+  async check(locator: Locator): Promise<void> {
+    if (!(await locator.isChecked())) {
+      await locator.check();
+    }
+  }
+
+  /**
+   * Uncheck a checkbox
+   * @param locator - The checkbox element
+   */
+  async uncheck(locator: Locator): Promise<void> {
+    if (await locator.isChecked()) {
+      await locator.uncheck();
+    }
+  }
+
+  /**
+   * Get text content from an element
+   * @param locator - The element to get text from
+   */
+  async getText(locator: Locator): Promise<string> {
+    return (await locator.textContent()) || '';
+  }
+
+  /**
+   * Check if element is visible
+   * @param locator - The element to check
+   */
+  async isVisible(locator: Locator): Promise<boolean> {
+    return await locator.isVisible();
+  }
+
+  /**
+   * Check if element is enabled
+   * @param locator - The element to check
+   */
+  async isEnabled(locator: Locator): Promise<boolean> {
+    return await locator.isEnabled();
+  }
+
+  /**
+   * Scroll element into view
+   * @param locator - The element to scroll to
+   */
+  async scrollIntoView(locator: Locator): Promise<void> {
+    await locator.scrollIntoViewIfNeeded();
+  }
+
+  /**
+   * Take a screenshot
+   * @param name - The screenshot file name
+   */
+  async takeScreenshot(name: string): Promise<void> {
+    await this.page.screenshot({ path: `screenshots/${name}.png`, fullPage: true });
+  }
+
+  /**
+   * Execute JavaScript in the browser context
+   * @param script - The script to execute
+   * @param args - Arguments to pass to the script
+   */
+  async executeScript<T>(script: string | Function, ...args: any[]): Promise<T> {
+    return await this.page.evaluate(script, ...args);
+  }
+
+  /**
+   * Wait for API response
+   * @param urlPattern - The URL pattern to wait for
+   */
+  async waitForResponse(urlPattern: string | RegExp): Promise<void> {
+    await this.page.waitForResponse(urlPattern);
+  }
+
+  /**
+   * Reload the current page
+   */
+  async reload(): Promise<void> {
+    await this.page.reload();
+  }
+
+  /**
+   * Go back in browser history
+   */
+  async goBack(): Promise<void> {
+    await this.page.goBack();
+  }
+
+  /**
+   * Go forward in browser history
+   */
+  async goForward(): Promise<void> {
+    await this.page.goForward();
+  }
+}

package/templates/playwright/auth.setup.template.ts

@@ -0,0 +1,89 @@
+import { test as setup, expect } from '@playwright/test';
+import path from 'path';
+import { mkdir } from 'fs/promises';
+
+/**
+ * Authentication Setup
+ * Generated by Bugzy - https://github.com/bugzy-ai/bugzy
+ *
+ * This file runs before all tests to authenticate and save the state
+ * Other tests can reuse this authenticated state for faster execution
+ *
+ * Benefits:
+ * - Login once, reuse for all tests
+ * - Faster test execution
+ * - More stable tests (no repeated login operations)
+ */
+
+const authFile = path.join(__dirname, '../.auth/user.json');
+
+setup('authenticate', async ({ page }) => {
+  // Skip if no authentication is needed
+  // Remove this if you need authentication
+  if (!process.env.TEST_USER_EMAIL || !process.env.TEST_USER_PASSWORD) {
+    console.log('Skipping authentication setup - no credentials provided');
+    return;
+  }
+
+  // Navigate to login page
+  // Adjust the URL based on your application
+  await page.goto('/login');
+
+  // Perform authentication steps
+  // Using role-based selectors for stability
+
+  // Fill in email
+  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL);
+
+  // Fill in password
+  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD);
+
+  // Click the sign in button
+  // Adjust the button text based on your app
+  await page.getByRole('button', { name: /sign in|login/i }).click();
+
+  // Wait for redirect after successful login
+  // Adjust the URL pattern based on where users land after login
+  await page.waitForURL(/.*\/(dashboard|home)/);
+
+  // Verify authentication was successful
+  // Check for a user-specific element (e.g., user menu, profile icon)
+  // Adjust based on your application
+  // await expect(page.getByRole('button', { name: /profile|account/i })).toBeVisible();
+
+  // Create .auth directory if it doesn't exist
+  await mkdir(path.dirname(authFile), { recursive: true });
+
+  // Save authentication state to file
+  await page.context().storageState({ path: authFile });
+
+  console.log('✓ Authentication state saved successfully');
+});
+
+/**
+ * Example: Multiple User Roles
+ *
+ * If you need to test with different user roles (admin, user, etc.),
+ * create separate setup files:
+ *
+ * - auth.setup.admin.ts
+ * - auth.setup.user.ts
+ * - auth.setup.guest.ts
+ *
+ * Then configure them in playwright.config.ts:
+ *
+ * projects: [
+ *   { name: 'setup-admin', testMatch: /.*\.setup\.admin\.ts/ },
+ *   { name: 'setup-user', testMatch: /.*\.setup\.user\.ts/ },
+ *   {
+ *     name: 'admin-tests',
+ *     use: { storageState: 'tests/.auth/admin.json' },
+ *     dependencies: ['setup-admin'],
+ *   },
+ *   {
+ *     name: 'user-tests',
+ *     use: { storageState: 'tests/.auth/user.json' },
+ *     dependencies: ['setup-user'],
+ *   },
+ * ]
+ */

package/templates/playwright/dataGenerators.helper.template.ts

@@ -0,0 +1,148 @@
+/**
+ * Test Data Generators
+ * Generated by Bugzy - https://github.com/bugzy-ai/bugzy
+ *
+ * Helper functions for generating realistic test data
+ */
+
+/**
+ * Generate a random email address
+ * @param prefix - Optional prefix for the email
+ */
+export function generateEmail(prefix = 'test'): string {
+  const timestamp = Date.now();
+  const random = Math.floor(Math.random() * 10000);
+  return `${prefix}-${timestamp}-${random}@example.com`;
+}
+
+/**
+ * Generate a random username
+ * @param prefix - Optional prefix for the username
+ */
+export function generateUsername(prefix = 'user'): string {
+  const timestamp = Date.now();
+  const random = Math.floor(Math.random() * 10000);
+  return `${prefix}_${timestamp}_${random}`;
+}
+
+/**
+ * Generate a random phone number (US format)
+ */
+export function generatePhoneNumber(): string {
+  const areaCode = Math.floor(Math.random() * 900) + 100;
+  const prefix = Math.floor(Math.random() * 900) + 100;
+  const lineNumber = Math.floor(Math.random() * 9000) + 1000;
+  return `(${areaCode}) ${prefix}-${lineNumber}`;
+}
+
+/**
+ * Generate a random string of specified length
+ * @param length - Length of the string
+ */
+export function generateRandomString(length: number): string {
+  const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += characters.charAt(Math.floor(Math.random() * characters.length));
+  }
+  return result;
+}
+
+/**
+ * Generate a random number between min and max (inclusive)
+ * @param min - Minimum value
+ * @param max - Maximum value
+ */
+export function generateRandomNumber(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Generate a random boolean value
+ */
+export function generateRandomBoolean(): boolean {
+  return Math.random() < 0.5;
+}
+
+/**
+ * Generate a unique ID
+ */
+export function generateUniqueId(): string {
+  return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Generate a random password
+ * @param length - Length of the password (default: 12)
+ */
+export function generatePassword(length = 12): string {
+  const uppercase = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+  const lowercase = 'abcdefghijklmnopqrstuvwxyz';
+  const numbers = '0123456789';
+  const special = '!@#$%^&*';
+  const all = uppercase + lowercase + numbers + special;
+
+  let password = '';
+  // Ensure at least one of each type
+  password += uppercase.charAt(Math.floor(Math.random() * uppercase.length));
+  password += lowercase.charAt(Math.floor(Math.random() * lowercase.length));
+  password += numbers.charAt(Math.floor(Math.random() * numbers.length));
+  password += special.charAt(Math.floor(Math.random() * special.length));
+
+  // Fill the rest
+  for (let i = password.length; i < length; i++) {
+    password += all.charAt(Math.floor(Math.random() * all.length));
+  }
+
+  // Shuffle the password
+  return password
+    .split('')
+    .sort(() => Math.random() - 0.5)
+    .join('');
+}
+
+/**
+ * Generate test user data
+ */
+export interface TestUser {
+  email: string;
+  username: string;
+  password: string;
+  firstName: string;
+  lastName: string;
+  phone: string;
+}
+
+export function generateTestUser(): TestUser {
+  const firstNames = ['John', 'Jane', 'Bob', 'Alice', 'Charlie', 'Diana', 'Eve', 'Frank'];
+  const lastNames = ['Smith', 'Johnson', 'Williams', 'Brown', 'Jones', 'Garcia', 'Miller', 'Davis'];
+
+  const firstName = firstNames[Math.floor(Math.random() * firstNames.length)];
+  const lastName = lastNames[Math.floor(Math.random() * lastNames.length)];
+
+  return {
+    email: generateEmail(firstName.toLowerCase()),
+    username: generateUsername(firstName.toLowerCase()),
+    password: generatePassword(),
+    firstName,
+    lastName,
+    phone: generatePhoneNumber(),
+  };
+}
+
+/**
+ * Pick a random item from an array
+ * @param array - Array to pick from
+ */
+export function pickRandom<T>(array: T[]): T {
+  return array[Math.floor(Math.random() * array.length)];
+}
+
+/**
+ * Generate a random date between two dates
+ * @param start - Start date
+ * @param end - End date
+ */
+export function generateRandomDate(start: Date, end: Date): Date {
+  return new Date(start.getTime() + Math.random() * (end.getTime() - start.getTime()));
+}