Blissium

AI-powered QA & testing agent that verifies your code changes work as intended before you push.

Blissium uses your diff & commit messages to automatically generate & run dynamic Playwright tests that verify your changes actually work and don't break anything.

Key Features

• 🤖 AI-Powered QA - Generates & runs relevant tests based on your diff & commit message
• 🐛 Catch Bugs Early - Finds issues before even opening a PR (not in CI/CD, staging, or production)
• ⚡ Lightning Fast - Takes 30-60 seconds for most commits
• 🆓 Self-Hosted, BYOK - Free to use, install, bring your own Anthropic API key & start immediately
• 🔄 Dynamic Test Execution - Tests generated on-demand, not added to your test suite by default
  • Optionally export as standalone Playwright test to include in your codebase
• 🔒 Privacy First - Your code never leaves your machine, no backend

Demo

🎥 Watch a 2-minute demo

Installation

npm install -g blissium

Quick Start

1. Initialize Blissium in your project

cd your-project
blissium init

This will:

• Create .blissium/ directory and config file
• Ask for your dev server URL (e.g., http://localhost:3000)
• Configure authentication if your app requires login (optional)

2. Set your Anthropic API key

export ANTHROPIC_API_KEY=sk-ant-...

Get your API key from https://console.anthropic.com/

Tip: Add this to your ~/.bashrc or ~/.zshrc to persist across sessions.

3. Make code changes and commit

# Make your changes
# ...

# Commit with a descriptive message
git add .
git commit -m "Add dark mode toggle to navbar"

4. Verify your changes

# Start your dev server first
npm run dev

# Then verify
blissium verify

Blissium will:

1. Read your latest commit message as the intent
2. Detect code changes via git diff
3. Generate Playwright tests
4. Run the tests against your dev server
5. Show you the results

Commands

blissium init

Initialize Blissium in your project.

Options: None

Example:

blissium init

blissium verify

Verify your code changes against the latest intent.

Options:

• --mock - Run basic mock tests instead of AI-generated tests (for debugging)
• --debug - Show verbose debug information including full intent and timing
• --rerun - Reuse saved test from last run (skip AI generation, save API costs)
• --headed - Run tests in headed mode (show browser window)
• --video - Record videos of test execution (saved to .blissium/videos/<commit-hash>/)
• --screenshots - Take screenshots on test failures (saved to .blissium/screenshots/<commit-hash>/)

Examples:

# Normal verification (AI-powered)
blissium verify

# Rerun last test (no API call)
blissium verify --rerun

# Mock mode (basic sanity checks only)
blissium verify --mock

# With debug output
blissium verify --debug

# Headed mode (show browser)
blissium verify --headed

# Record video of test execution
blissium verify --video

# Take screenshots on test failures
blissium verify --screenshots

# Record video and take screenshots
blissium verify --video --screenshots

blissium show-tests

List all saved tests or view a specific test.

Usage:

# List all saved tests
blissium show-tests

# View specific test by commit hash
blissium show-tests a1b2c3d4

Output:

• Lists all saved tests with commit hash, message, and timestamp
• Shows full test code when viewing specific test

blissium export-test

Export a saved test to a standalone Playwright test file for debugging.

Usage:

# Export latest commit's test (with confirmation prompt)
blissium export-test

# Export specific commit's test
blissium export-test a1b2c3d4

# Interactively select which test cases to include
blissium export-test --select

# Export to custom location
blissium export-test a1b2c3d4 tests/my-test.spec.js

Options:

• --select - Interactively choose which test cases to include in the export

What it does:

• Converts Blissium test to standard Playwright test format
• Includes authentication logic if configured
• Can be run with Playwright's debugging tools
• With --select: Shows checkbox list to pick specific test cases

Benefits:

• Debug tests step-by-step with --debug flag
• See browser interactions in headed mode
• Modify and iterate on tests locally
• Use Playwright's full testing features
• Remove irrelevant test cases before exporting

blissium edit-test

Interactively modify a saved test using natural language with AI assistance.

Usage:

# Edit latest commit's test (with confirmation prompt)
blissium edit-test

# Edit specific commit's test
blissium edit-test a1b2c3d4

What it does:

• Loads an existing saved test
• Shows test summary and test case names
• Interactive menu with options to:
  • Make changes using natural language
  • View current test code
  • Run the test to verify changes
  • Save modifications
  • Exit with or without saving

Example conversation:

$ blissium edit-test

Current Test Summary:
  Commit: a1b2c3d4
  Message: Add dark mode toggle
  Test cases: 3
    1. Dark mode toggle button exists
    2. Dark mode toggle changes theme
    3. Dark mode preference persists after reload

What would you like to do?
> Make changes to the test

What changes would you like to make to this test?
> Add a test to verify the toggle icon changes

[AI generates modified test with new test case]

Changes:
  + // Test 4: Verify toggle icon changes between sun and moon
  + try {
  +   const toggleIcon = await page.locator('[data-testid="theme-toggle-icon"]');
  +   ...
  + }

Apply these changes?
> Yes, apply changes

Changes applied!

What would you like to do?
> Run the test

[Test runs and shows results]

What would you like to do?
> Save and exit

Test saved successfully!

Benefits:

• No need to manually edit test code
• AI understands context from original test
• Make multiple iterative changes
• Test modifications before saving
• Conversational interface for quick edits

Common use cases:

• Add new test cases: "Add a test for the delete button"
• Modify timeouts: "Increase all timeouts to 10 seconds"
• Change selectors: "Use data-testid attributes instead of class names"
• Remove tests: "Remove the test for pagination"
• Fix failing tests: "Make the login selector more specific"

How It Works

1. Commit Your Changes: You make changes and commit with a descriptive message (e.g., "Add dark mode toggle")
2. Intent Capture: Blissium reads your latest commit message as the development intent
3. Code Analysis: Blissium detects what changed via git diff
4. Test Generation: Blissium generates Playwright tests that verify your intent was correctly implemented
5. Verification: Tests run against your dev server to check everything works
6. Auto-Correction: If tests fail, Blissium automatically analyzes the failures and regenerates corrected tests once
7. Results: Clear pass/fail report with error details

Smart Test Reliability

Blissium uses intelligent test generation with automatic error correction:

• Authentication-aware: Uses your exact credentials and selectors from config
• Auto-retry: Failed tests are automatically analyzed and corrected once
• Post-processing: Common test mistakes are automatically fixed (URL checks, timeouts, selectors)
• Smart waits: Handles client-side redirects and dynamic content properly

This means fewer false test failures and more reliable verification.

Configuration

Configuration is stored in .blissium/config.json:

{
  "serverUrl": "http://localhost:3000",
  "auth": {
    "required": true,
    "loginUrl": "/login",
    "usernameSelector": "#email",
    "passwordSelector": "#password",
    "submitSelector": "button[type='submit']",
    "testUsername": "[email protected]",
    "testPassword": "test123"
  }
}

Fields:

• serverUrl - URL of your development server
• auth (optional) - Authentication configuration for apps that require login
  • required - Whether authentication is needed
  • loginUrl - Path to login page (relative to serverUrl)
  • usernameSelector - CSS selector for username/email field
  • passwordSelector - CSS selector for password field
  • submitSelector - CSS selector for submit button
  • testUsername - Test account username/email
  • testPassword - Test account password

Authentication Setup

If your app requires authentication, Blissium will automatically:

1. Detect login form fields during blissium init
2. Store the credentials securely in .blissium/config.json
3. Authenticate before running any tests during blissium verify

Important: Make sure to add .blissium/ to your .gitignore to avoid committing credentials:

echo ".blissium/" >> .gitignore

Requirements

• Node.js 18 or higher
• A development server (for your web app)
• Anthropic API key
• Git repository (required for commit-based intents)

Pricing

Blissium is free to use. You only pay for your Anthropic API usage (~$0.01-0.05 per verification.)

No subscription, no backend.

Troubleshooting

"ANTHROPIC_API_KEY environment variable is not set"

Set your API key:

export ANTHROPIC_API_KEY=sk-ant-...

To make it permanent, add to your shell profile:

echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
source ~/.zshrc

"Dev server not responding"

Make sure your dev server is running:

npm run dev  # or yarn dev, pnpm dev, etc.

Then verify the URL in .blissium/config.json matches your server.

"No git commits found"

Make sure you have committed your changes:

git add .
git commit -m "Describe what you changed"

Blissium uses your commit message as the intent for verification.

Tests are failing but the feature works

Blissium automatically retries failed tests once with error context to fix test bugs. If tests still fail after auto-correction:

Common causes:

• The commit message was vague or unclear
• The git diff doesn't show the relevant changes
• The feature has actual bugs that need fixing

Debug steps:

1. Run with --debug to see what commit message was used:

   blissium verify --debug

2. Run with --headed to watch the tests execute:

   blissium verify --headed

3. Check the saved test file in .blissium/tests/ to review what was tested

Tip: Write clear, descriptive commit messages that explain what the change does.

"Authentication failed"

If authentication is failing:

1. Verify your dev server is running and the login page is accessible
2. Check the credentials in .blissium/config.json are correct
3. Test the selectors manually - open your browser's DevTools and verify the CSS selectors match your login form fields
4. Run in headed mode to see what's happening:

   blissium verify --headed

5. Try manual configuration - edit .blissium/config.json with the correct selectors:

   {
     "auth": {
       "required": true,
       "loginUrl": "/login",
       "usernameSelector": "input[name='email']",
       "passwordSelector": "input[type='password']",
       "submitSelector": "button[type='submit']"
     }
   }

Common issues:

• Login form uses dynamic selectors (try more stable selectors like data-testid)
• Page requires JavaScript to load (increase timeout in code)
• Login requires additional steps (captcha, 2FA) - not currently supported

Examples

Basic workflow

# Initialize
cd my-react-app
blissium init

# Set API key
export ANTHROPIC_API_KEY=sk-ant-...

# Make your changes
# ...

# Commit your changes
git add .
git commit -m "Add dark mode toggle with localStorage persistence"

# Start dev server
npm run dev

# Verify changes
blissium verify

Workflow with authentication

# Initialize with authentication
cd my-app
blissium init
# ? What URL is your dev server running on? localhost:3000
# ? Does your app require authentication/login to access pages? Yes
# ? Login page URL: /login
# (Blissium auto-detects login form)
# ? Test username/email: [email protected]
# ? Test password: test123

# Set API key
export ANTHROPIC_API_KEY=sk-ant-...

# Make your changes to authenticated pages
# ...

# Commit your changes
git add .
git commit -m "Add user profile edit functionality"

# Start dev server
npm run dev

# Verify changes (authentication happens automatically)
blissium verify

CI/CD Integration

# .github/workflows/verify.yml
name: Verify Changes
on: [push]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install
      - run: npm run build
      - run: npm run dev & # Start server in background
      - run: npx blissium verify
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Advanced Usage

Debug Mode

See detailed information about the verification:

blissium verify --debug

This shows:

• Mode (AI-powered or mock)
• Server URL
• Commit timestamp and message
• Files that were changed
• Total execution time
• Saved test file location

Generated Test Files

Blissium saves all generated tests to .blissium/tests/ for debugging and review:

.blissium/tests/
  ├── a1b2c3d4.js    # Test for commit a1b2c3d4
  ├── e5f6g7h8.js    # Test for commit e5f6g7h8
  └── ...

Each file contains:

• The generated Playwright test code
• Commit hash, message, and timestamp
• List of files that were changed

Benefits:

• Review what tests were generated
• Debug test failures
• Rerun tests without API costs (--rerun flag)
• Understand AI's test strategy
• Share tests with team members

Commands:

# List all saved tests
blissium show-tests

# View specific test
blissium show-tests a1b2c3d4

# Rerun last test (no API call)
blissium verify --rerun

# Export test to standalone Playwright file (latest commit)
blissium export-test

# Or export specific commit
blissium export-test a1b2c3d4

These files are automatically ignored by git (in .gitignore).

Debugging Tests

When a test fails, you can export it to a standalone Playwright test for detailed debugging:

# Export the latest test (or specify commit hash)
blissium export-test

# Selectively export only relevant test cases
blissium export-test --select
# Shows interactive checkbox to choose which tests to include

# Run with Playwright's debugger
npx playwright test tests/<commit-hash>.spec.js --debug

This gives you:

• Step-by-step execution with breakpoints
• Visual browser inspection
• Full Playwright debugging tools
• Ability to modify and iterate on the test
• Option to remove irrelevant test cases with --select

The exported test includes authentication logic automatically if configured.

Video and Screenshot Artifacts

Blissium can capture videos and screenshots during test execution to help debug failures:

# Record video of test execution
blissium verify --video

# Take screenshots on test failures
blissium verify --screenshots

# Combine both
blissium verify --video --screenshots --headed

Artifacts are saved to:

• Videos: .blissium/videos/<commit-hash>/
  • initial-run.webm - First test execution
  • retry-run.webm - Auto-retry execution (if tests failed and were regenerated)
• Screenshots: .blissium/screenshots/<commit-hash>/
  • Screenshots are only saved from the final test run
  • If auto-retry happens, only screenshots from the retry are saved (tests that were fixed won't have screenshots)
  • If no retry, screenshots are saved from the initial run
  • Format: test-1-<test-name>.png or retry-test-1-<test-name>.png

Benefits:

• Visual debugging of test failures
• See exactly what the browser was doing when tests failed
• Compare initial vs. retry videos to understand what changed
• Only shows failures that persist after retry (no clutter from fixed tests)
• Share artifacts with team members
• Review test execution without rerunning

Notes:

• Videos are recorded in WebM format at 1280x720 resolution
• Screenshots are taken as full-page PNG images
• Only failed tests get screenshots (to save disk space)
• Screenshots only show tests that failed in the final run (after auto-retry if applicable)
• Video recording works in both headless and headed mode
• Artifacts are organized by commit hash for easy identification
• When auto-retry runs, you'll have both initial and retry videos for comparison

Mock Mode

Run basic sanity checks without AI:

blissium verify --mock

Useful for:

• Testing Blissium itself
• Quick smoke tests without API costs
• Debugging server connectivity issues

Authentication for Protected Apps

If your application requires users to log in before accessing pages, Blissium can automatically handle authentication:

During initialization:

blissium init
# ? What URL is your dev server running on? localhost:3000
# ? Does your app require authentication/login to access pages? Yes
# ? Login page URL (relative to server URL): /login
# Auto-detecting login form fields...
# ✓ Successfully detected login form fields!
#   • Username field: #email
#   • Password field: #password
#   • Submit button: button[type='submit']
# ? Use these detected selectors? Yes
# ? Test username/email: [email protected]
# ? Test password: ********

What happens:

1. Blissium launches a browser and visits your login page
2. Automatically detects username, password, and submit button selectors
3. Lets you confirm or manually adjust the selectors
4. Securely stores test credentials in .blissium/config.json

During verification:

• Blissium automatically logs in before running any tests
• Uses the saved credentials from config
• Tests run as an authenticated user
• Authentication failure stops the test run with clear error messages

Manual configuration: If auto-detection fails, you can manually edit .blissium/config.json:

{
  "serverUrl": "http://localhost:3000",
  "auth": {
    "required": true,
    "loginUrl": "/auth/login",
    "usernameSelector": "input[name='email']",
    "passwordSelector": "input[name='password']",
    "submitSelector": "button.login-btn",
    "testUsername": "[email protected]",
    "testPassword": "securepassword123"
  }
}

Security notes:

• Test credentials are stored locally in .blissium/config.json
• Always add .blissium/ to .gitignore to prevent committing credentials
• Use a dedicated test account, not production credentials
• Consider using environment variables for CI/CD (see CI/CD Integration)

Privacy & Security

• ✅ Your code stays on your machine
• ✅ Uses git commit messages (already part of your workflow)
• ✅ Direct API calls to Anthropic (no intermediary)
• ✅ API key stored in environment variable (not committed to git)
• ✅ Anonymous usage telemetry (opt-out available, see Telemetry)

Telemetry

Blissium collects anonymous usage data to help us improve the tool. We track:

• Commands used and their success/failure rates
• Feature usage (e.g., --headed, --video flags)
• System information (OS, Node version, CLI version)
• Anonymous user ID and location (country/region level)

We do not collect:

• Your code, diffs, or commit messages
• File paths or names
• Server URLs or credentials
• Any personally identifiable information

To disable telemetry, edit .blissium/config.json and add:

{
  "telemetryEnabled": false
}

Telemetry helps us understand how Blissium is used and prioritize improvements. All data is anonymous and never sold or shared with third parties.

Roadmap

• MCP server for automatic intent logging
• Test result caching
• Custom test templates
• Integration with existing test frameworks
• Support for pre-commit verification (before committing)

Contributing

Issues and feature requests: https://github.com/bliss-labs-ai/blissium/issues