Skip to content

getting-started.md

Latest commit

 

History

History
277 lines (201 loc) · 8.5 KB

getting-started.md

File metadata and controls

277 lines (201 loc) · 8.5 KB
Raw

Getting Started with Bugzy

Bugzy is an open-source CLI tool that manages AI agent configuration for your AI coding assistant, making it easy to set up powerful QA automation workflows.

Installation

Install Bugzy globally using npm:

npm install -g bugzy

Verify the installation:

bugzy --version

Prerequisites

Before using Bugzy, ensure you have:

  1. AI Coding Tool - One of the following installed and configured:
    • Claude Code (recommended) - Anthropic's official CLI
    • Cursor (experimental) - VS Code-based AI editor
    • Codex CLI (experimental) - OpenAI's terminal-based agent
  2. Node.js (v18 or higher)
  3. Access to your project repository

Note: Cursor and Codex support is experimental. Some features may not work as expected. Claude Code is the recommended option.

First-Time Setup

Step 1: Navigate to Your Project

cd /path/to/your/project

Bugzy works with any project type - Node.js, Python, Ruby, Go, etc. No package.json required!

Step 2: Run Setup

bugzy setup

This launches an interactive setup wizard that will:

  • Ask which AI coding tool you use (Claude Code, Cursor, or Codex)
  • Create the .bugzy/ directory structure
  • Create the tool-specific directory (.claude/, .cursor/, or .codex/)
  • Prompt you to configure subagents
  • Generate task commands
  • Generate MCP configuration
  • Create an .env.testdata file with required secrets

Step 3: Configure Subagents

The setup wizard will ask you to configure subagents. Here's what each one does:

Test Runner (Required)

  • Purpose: Execute automated tests
  • Options: Playwright (local, no secrets needed)
  • Recommendation: Choose Playwright for browser testing

Test Code Generator (Required)

  • Purpose: Generate Playwright test scripts and Page Objects
  • Options: Playwright (local, no secrets needed)
  • Recommendation: Automatically configured with Test Runner

Test Debugger & Fixer (Required)

  • Purpose: Debug and fix failing tests automatically
  • Options: Playwright (local, no secrets needed)
  • Recommendation: Automatically configured with Test Runner

Team Communicator (Required)

  • Purpose: Send notifications to your team
  • CLI: Auto-configured to use terminal (no setup needed)
  • Cloud Options: Slack, Microsoft Teams, Email (fallback)
  • Recommendation: For CLI, just run setup - it's automatic. For cloud, choose Slack or Teams for rich notifications.

Documentation Researcher (Optional)

  • Purpose: Search and retrieve documentation
  • Options: Notion, None
  • Recommendation: Choose Notion if your team uses it for documentation

Issue Tracker (Optional)

  • Purpose: Create and track bugs automatically
  • Options: Jira Server, Notion, Slack, None
  • Recommendation: Choose your team's issue tracking tool

Step 4: Configure Environment Variables

After setup completes, you'll have a .env.testdata file with placeholders for required secrets:

# Copy the example file
cp .env.testdata .env

# Edit .env and add your secrets
vim .env

Example .env file:

# Slack (if configured)
SLACK_BOT_TOKEN=xoxb-your-token-here

# Notion (if configured)
NOTION_TOKEN=secret_your-token-here

# Test configuration
TEST_BASE_URL=http://localhost:3000
[email protected]
TEST_USER_PASSWORD=your-password

Getting API Tokens

Starting Your First Session

Once setup is complete, start a Bugzy session:

bugzy

This will:

  1. Load your configuration
  2. Validate environment variables
  3. Launch your AI coding tool with all configured subagents

You can also start with an initial prompt:

bugzy "generate test plan for user authentication"

Project Structure

After setup, your project will have this structure:

your-project/
├── .bugzy/
│   ├── config.json              # Internal configuration (do not edit manually)
│   └── runtime/
│       ├── project-context.md   # Edit this with project details
│       └── templates/
│           └── test-plan-template.md  # Customize test plan format
├── .<tool>/                     # Tool-specific directory (.claude/, .cursor/, or .codex/)
│   ├── commands/                # Generated task commands (or prompts/ for Codex)
│   │   ├── generate-test-plan.md
│   │   ├── run-tests.md
│   │   └── ... (more tasks)
│   ├── agents/                  # Generated subagent configurations
│   │   ├── test-runner.md
│   │   ├── team-communicator.md
│   │   └── ...
│   └── mcp.json                # MCP server configuration
├── .env.testdata                # Template for environment variables
└── .env                        # Your secrets (gitignored)

Note: The directory structure varies by tool. Claude Code uses .claude/, Cursor uses .cursor/, and Codex uses .codex/.

What You Can Edit

  • ✅ .bugzy/runtime/project-context.md - Add project details, tech stack, testing approach
  • ✅ .bugzy/runtime/templates/test-plan-template.md - Customize test plan format
  • ✅ .env - Add your API tokens and secrets
  • ❌ .bugzy/config.json - Don't edit manually, use bugzy setup to reconfigure
  • ❌ .<tool>/ (.claude/, .cursor/, .codex/) - Don't edit manually, regenerated by bugzy setup

Using Tasks

Bugzy provides 8 built-in tasks (available as slash commands):

  • /generate-test-plan - Create comprehensive test plans
  • /generate-test-cases - Generate specific test cases
  • /explore-application - Explore and document your application
  • /run-tests - Execute automated tests
  • /verify-changes - Verify changes with smart output routing
  • /onboard-testing - Complete workflow: explore → plan → cases → test → fix → report
  • /handle-message - Process team messages from Slack/Teams
  • /process-event - Handle automated webhooks and events

Note: Command invocation varies by tool. Claude Code and Cursor use /command, while Codex uses /prompts:command.

Common Workflows

Generate and Run Tests

# Start Bugzy
bugzy

# In your AI coding tool:
/generate-test-plan for login flow
/generate-test-cases based on the test plan
/run-tests for login

Report Issues

bugzy "explore the checkout flow and create a test plan"

# In your AI coding tool:
/run-tests for checkout
# If issues found, they'll be reported to your configured issue tracker

Troubleshooting

Missing Secrets Error

✗ Missing required MCP secrets:
  - SLACK_BOT_TOKEN
  - NOTION_TOKEN

Solution: Add the missing secrets to your .env file.

AI Tool Not Found

Error: <tool> command not found

Solution: Install your selected AI coding tool and ensure it's in your PATH:

Invalid Configuration

Error: Could not load .bugzy/config.json

Solution: Run bugzy setup to recreate the configuration.

Template Files Not Found

Error: Cannot find template at path/to/template

Solution: This usually means Bugzy wasn't installed correctly. Try reinstalling:

npm uninstall -g bugzy
npm install -g bugzy

Next Steps

  • Customize your project: Edit .bugzy/runtime/project-context.md with project details
  • Configure integrations: Add all your API tokens to .env
  • Learn about subagents: Read Subagents Guide
  • Explore tasks: Read Task Library
  • Reconfigure: Run bugzy setup anytime to change your configuration

Getting Help