If Setup is Required (setupComplete: false)

When setupComplete is false, check the prerequisites in setup.json and complete the following:

1. Install Bugster CLI (if bugsterCli.installed: false)

# Install Bugster CLI
curl -sSL https://bugster.dev/install.sh | bash

# Verify installation
bugster --version

# If successful, update setup.json: set prerequisites.bugsterCli.installed to true

2. Configure API Key (if apiKey.configured: false)

CRITICAL: Check if~/.bugsterrc exists and contains a valid API key:

# Check if ~/.bugsterrc exists
cat ~/.bugsterrc

If~/.bugsterrc does NOT exist or is missing the apiKey field:

1. Ask the user to provide their Bugster API key :

   • Prompt: "I need your Bugster API key to continue. Please provide your API key (you can find it at https://bugster.dev):"
   • Wait for the user to provide the API key

2. Create~/.bugsterrc file with the provided API key:

   {
     "apiKey": "user_provided_key_here"
   }
   

3. Verify the file was created successfully

4. Update setup.json : set prerequisites.apiKey.configured to true

3. Mark Setup Complete

Once both bugsterCli.installed and apiKey.configured are true in setup.json, set setupComplete to true.

Project Initialization Check

CRITICAL: After setup is complete, check if the project has been initialized:

1. Check if.bugster directory exists in the user's project root
2. If.bugster directory does NOT exist:
   • You MUST run bugster init first (see steps below)
   • This creates necessary configuration files and project structure
   • Without this, bugster generate and bugster run will fail
3. If.bugster directory exists: Proceed with generate/run commands

Initialize Project (REQUIRED Before First Use)

Every time you work with a new project , after verifying setup is complete and API key is configured, check if .bugster directory exists.

If.bugster directory does NOT exist, you must collect the following information from the user:

1. Application URL :

   • Prompt: "What URL is your application running on? (e.g., http://localhost:3000, http://localhost:3001, etc.):"
   • Wait for the user to provide the URL

2. Login Credentials (if applicable):

   • Ask: "Does your application have a login page that needs to be bypassed for testing?"
   • If YES:
     • Prompt: "Please provide the username/email for login:"
     • Wait for the user to provide the username
     • Prompt: "Please provide the password for login:"
     • Wait for the user to provide the password
   • If NO: Skip credential collection

3. Run non-interactivebugster init:

# With login credentials:

bugster init --api-key="$(cat ~/.bugsterrc | grep apiKey | cut -d'"' -f4)" --url="<user_provided_url>" --user="<user_provided_username>" --password="<user_provided_password>"

# Without login credentials (no login page):
bugster init --api-key="$(cat ~/.bugsterrc | grep apiKey | cut -d'"' -f4)" --url="<user_provided_url> --no-credentials"

Alternative (if you already have the API key in a variable):

# With login credentials:
bugster init --api-key="<api_key>" --url="<url>" --user="<user>" --password="<password>"

# Without login credentials:
bugster init --api-key="<api_key>" --url="<url>" --no-credentials

This non-interactive approach ensures fast execution without manual prompts.

The.bugster directory must exist before running bugster generate or bugster run.

Prerequisites Summary

Before running any Bugster commands, ensure all prerequisites are met:

• ✅ Bugster CLI installed and available in PATH (prerequisites.bugsterCli.installed: true in setup.json)
• ✅ Bugster API key configured in ~/.bugsterrc (prerequisites.apiKey.configured: true in setup.json)
• ✅ Setup marked as complete (setupComplete: true in setup.json)
• ✅ Node.js 18+ installed on your system
• ✅ Application URL collected from user
• ✅ Login credentials collected from user (if application has login page)
• ✅ .bugster directory exists in project root (created by non-interactive bugster init)

CRITICAL WORKFLOW:

1. Check setup.json:
   • If setupComplete: false, complete all prerequisites in setup.json
   • If bugsterCli.installed: false, install Bugster CLI
   • If apiKey.configured: false, check for ~/.bugsterrc and ask user for API key if needed
   • Once all prerequisites are met, set setupComplete: true
2. Check for .bugster directory in project root:
   • If missing, collect application URL and login credentials from user
   • Run non-interactive bugster init --api-key=<key> --url=<url> with --user=<user> --password=<password> if credentials were provided or with --no-credentials if they were not
3. Only then proceed with bugster generate or bugster run commands

DO NOT attempt to runbugster generate or bugster run without completing all prerequisite checks.

Available Commands

Generate Tests

bugster generate [options]

When to use : Analyzing codebase and automatically generating test specifications, creating test suites, generating test scenarios.

Options :

• --count <number>: Number of test specs to generate per page (range: 1-30)
• --page <paths>: Generate specs only for specific page files (comma-separated paths)
• --prompt <text>: Custom prompt to guide AI test generation (must be used with --page)

Example usage :

• bugster generate
• bugster generate --count 10
• bugster generate --page "pages/product.tsx" --prompt "Focus on edge cases and error handling"
• bugster generate --page "pages/login.tsx,pages/signup.tsx" --count 5

Output : Test specifications saved in .bugster/tests/ directory with JSON format

Run Tests

bugster run [path] [options]

When to use : Executing test specifications, validating functionality, running test suites, performing automated testing.

CRITICAL: Before runningbugster run, ALWAYS ask the user which type of test execution they want:

1. Run all test files (default):

   • Ask: "Do you want to run all test files?"
   • If YES: bugster run [options]

2. Run specific test file(s) :

   • Ask: "Do you want to run a specific test file?"
   • If YES: "Please provide the path to the test file (e.g., .bugster/tests/login-test.json):"
   • Use: bugster run --path <user_provided_path> [options]

3. Run custom prompt test (instant test without generating specs):

   • Ask: "Do you want to run a custom test from a natural language description?"
   • If YES: "Please describe the test you want to run:"
   • Use: bugster run "<user_provided_prompt>" [options]

Options :

• --headless: Run tests in headless mode without visible browser UI (ideal for CI/CD)
• --parallel <number>: Maximum number of concurrent tests (default: 3)
• --limit <number>: Maximum number of tests to execute
• --browser <name>: Browser engine to use (chromium, firefox, or webkit)

Example usage :

• bugster run (all test files)
• bugster run --headless --parallel 8 (all test files, headless mode)
• bugster run --path .bugster/tests/login-test.json (specific file)
• bugster run --path .bugster/tests/checkout-test.json --browser firefox (specific file with browser)
• bugster run "Test user login with valid credentials and verify dashboard loads" (custom prompt)
• bugster run "Test checkout flow with valid payment details" --headless (custom prompt, headless)

Important : Custom prompt tests allow running instant tests without generating specifications first. This is useful for quick validation and ad-hoc testing.

Output : Test results including pass/fail status, screenshots, video recordings, and detailed logs

Test Workflow

Standard workflow : The typical testing flow uses both commands sequentially:

1. Generate test specifications with bugster generate
2. Execute tests with bugster run

Quick testing : For rapid validation, use bugster run <custom_prompt> to execute tests directly without generating specifications.

Iterative testing : After code changes, regenerate tests with bugster generate and validate with bugster run.

Best Practices

1. Verify prerequisites : ALWAYS check setup.json to ensure setupComplete: true before running any Bugster commands
2. Check API key first : Verify ~/.bugsterrc exists with a valid API key (prerequisites.apiKey.configured: true)
3. Non-interactive initialization : Collect application URL and login credentials upfront, then run bugster init with all flags for fast, non-interactive setup
4. Check for initialization : ALWAYS verify .bugster directory exists before running any commands. If missing, collect required info and run non-interactive bugster init
5. Ask before running tests : ALWAYS ask the user which type of test execution they want (all files, specific file, or custom prompt) before running bugster run
6. Use natural language : Leverage custom prompts with clear, specific instructions for AI-powered testing
7. Optimize execution : Use --parallel to speed up test runs, and --limit for quick validation
8. Version control : Commit the .bugster/ directory to maintain consistent test configurations across your team (but NOT ~/.bugsterrc which contains sensitive API keys)
9. Target specific pages : Use --page with generate to focus on critical user flows
10. Headless for CI/CD : Always use --headless flag in continuous integration environments
11. Review outputs : Check test results, logs, and screenshots to identify and address issues promptly
12. Iterate regularly : Regenerate tests after significant code changes to keep test coverage current

Common Patterns

Generate and run complete test suite

bugster generate
bugster run

Generate focused tests for critical pages

bugster generate --page "pages/checkout.tsx,pages/payment.tsx" --count 5 --prompt "Focus on payment processing and security"

Run tests in CI/CD environment

bugster run --headless --parallel 5

Quick ad-hoc validation

bugster run "Verify the contact form submits successfully and displays a confirmation message"

Debug specific test with browser visible

bugster run --path .bugster/tests/checkout-test.json --limit 1

Generate comprehensive test suite

bugster generate --count 20
bugster run --headless --parallel 10

Using Hooks for Specific Data

When tests require specific data that must be fetched or computed before execution (such as database IDs, account references, or dynamic values), use hooks to define helper functions that run before the test.

Hook Structure

Hooks allow you to:

• Run helper functions before test execution (before hooks)
• Pass arguments to helper functions
• Store results in variables for use in test steps

Hook Configuration Format

name: <test_name>
page: <page_route>
page_path: <path_to_page_file>
hooks:
  before:
    - helper: <helper_function_name>
      file_path: <path_to_helper_file>
      args: [<arg1>, <arg2>, ...]
      as: <variable_name>
task: <test_description>
steps:
  - <step_1>
  - <step_2>
expected_result: <expected_outcome>

Hook Fields

Example: Test with Data Hooks

name: User creates optional concept without attributes
page: /conceptos
page_path: apps/e2e/pages/dashboard/conceptsPage.ts
hooks:
  before:
    - helper: getSchoolIdByName
      file_path: apps/e2e/helpers/commons.ts
      args: ["Instituto Internacional Carlos"]
      as: schoolId
    - helper: getBankAccountBySchoolName
      file_path: apps/e2e/helpers/commons.ts
      args: ["Instituto Internacional Carlos"]
      as: bankAccount
task: Verify user can create optional concept with IVA billing
steps:
  - Login as automata@getcome.com with pass
  - Navigate to concepts page
  - Click on "Create Concept" button
  - Fill in concept details using {{schoolId}} and {{bankAccount}}
  - Submit the form
expected_result: Success message displays, concept visible in concepts table

Multiple Before Hooks

You can chain multiple before hooks that execute sequentially:

hooks:
  before:
    - helper: createTestUser
      file_path: apps/e2e/helpers/users.ts
      args: ["test@example.com", "TestUser123"]
      as: userId
    - helper: assignRoleToUser
      file_path: apps/e2e/helpers/roles.ts
      args: ["{{userId}}", "admin"]
      as: roleAssignment
    - helper: getAuthToken
      file_path: apps/e2e/helpers/auth.ts
      args: ["{{userId}}"]
      as: authToken

Best Practices for Hooks

1. Reference existing helpers : Always point file_path to actual helper files in your codebase
2. Use descriptive variable names : The as field should clearly indicate what data is stored
3. Chain dependencies : Later hooks can reference variables from earlier hooks using {{variable_name}}
4. Keep helpers focused : Each helper should do one thing well
5. Document helper functions : Ensure helper files have clear documentation for available functions

When to Use Hooks

Use hooks when your test requires:

• Database IDs that vary between environments
• Dynamic data that must be fetched at runtime
• Pre-test setup (creating test users, seeding data)
• Authentication tokens or session data
• Any data that cannot be hardcoded in the test specification

Troubleshooting

Command not found : Ensure Bugster CLI is installed and added to PATH. Check setup.json - if prerequisites.bugsterCli.installed: false, run curl -sSL https://bugster.dev/install.sh | bash to install

Authentication issues : Verify your Bugster API key is configured correctly in ~/.bugsterrc. Check setup.json - if prerequisites.apiKey.configured: false, you need to:

1. Check if ~/.bugsterrc exists and contains a valid apiKey field
2. If missing, ask the user to provide their API key and create the file
3. Update setup.json to set prerequisites.apiKey.configured: true

Project not initialized /.bugster directory missing: Check if .bugster directory exists in project root. If not:

1. Collect application URL from user (e.g., http://localhost:3000)
2. Ask if login page exists and collect credentials if needed
3. Run non-interactive: bugster init --api-key=<key> --url=<url> --user=<user> --password=<password>
4. Or without login: bugster init --api-key=<key> --url=<url> --no-credentials

Test failures : Review detailed logs and screenshots in test output. Use bugster run --limit 1 to debug individual tests

No tests found : Ensure you've run bugster generate first, or use bugster run <custom_prompt> for instant testing

Browser issues : Try different browsers with --browser option or ensure required browsers are installed

For detailed examples, see EXAMPLES.md. For API reference and technical details, see REFERENCE.md.

Dependencies

To use this skill, ensure Bugster CLI is installed:

# Install Bugster CLI
curl -sSL https://bugster.dev/install.sh | bash

# Verify installation
bugster --version

Requirements :

• Node.js 18 or higher
• Supported browsers (Chromium, Firefox, or WebKit)
• Valid Bugster API key

Weekly Installs

0

Repository

bugsterapp/agent-test

First Seen

Jan 1, 1970

Security Audits

Gen Agent Trust HubFailSocketFailSnykFail