AI-powered QA & testing agent for web developers
npm install 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.
- š¤ 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
``bash`
npm install -g blissium
`bash`
cd your-project
blissium init
This will:
- Create .blissium/ directory and config filehttp://localhost:3000
- Ask for your dev server URL (e.g., )
- Configure authentication if your app requires login (optional)
`bash`
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.
`bashMake your changes
...
$3
bash
Start your dev server first
npm run devThen 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
$3
Initialize Blissium in your project.
Options: None
Example:
bash
blissium init
`$3
Verify your code changes against the latest intent.
Options:
-
- 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/)
- --screenshots - Take screenshots on test failures (saved to .blissium/screenshots/)Examples:
`bash
Normal verification (AI-powered)
blissium verifyRerun last test (no API call)
blissium verify --rerunMock mode (basic sanity checks only)
blissium verify --mockWith debug output
blissium verify --debugHeaded mode (show browser)
blissium verify --headedRecord video of test execution
blissium verify --videoTake screenshots on test failures
blissium verify --screenshotsRecord video and take screenshots
blissium verify --video --screenshots
`$3
List all saved tests or view a specific test.
Usage:
bash
List all saved tests
blissium show-testsView 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
$3
Export a saved test to a standalone Playwright test file for debugging.
Usage:
bash
Export latest commit's test (with confirmation prompt)
blissium export-testExport specific commit's test
blissium export-test a1b2c3d4Interactively select which test cases to include
blissium export-test --selectExport to custom location
blissium export-test a1b2c3d4 tests/my-test.spec.js
`Options:
-
- Interactively choose which test cases to include in the exportWhat 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 casesBenefits:
- 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$3
Interactively modify a saved test using natural language with AI assistance.
Usage:
`bash
Edit latest commit's test (with confirmation prompt)
blissium edit-testEdit 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:
bash
$ blissium edit-testCurrent 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
$3
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
:`json
{
"serverUrl": "http://localhost:3000",
"auth": {
"required": true,
"loginUrl": "/login",
"usernameSelector": "#email",
"passwordSelector": "#password",
"submitSelector": "button[type='submit']",
"testUsername": "test@example.com",
"testPassword": "test123"
}
}
`Fields:
-
- 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$3
If your app requires authentication, Blissium will automatically:
1. Detect login form fields during
blissium init
2. Store the credentials securely in
3. Authenticate before running any tests during Important: Make sure to add
to your .gitignore to avoid committing credentials:
`bash
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
$3
Set your API key:
bash
export ANTHROPIC_API_KEY=sk-ant-...
`To make it permanent, add to your shell profile:
bash
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
source ~/.zshrc
`$3
Make sure your dev server is running:
bash
npm run dev # or yarn dev, pnpm dev, etc.
`Then verify the URL in
matches your server.$3
Make sure you have committed your changes:
`bash
git add .
git commit -m "Describe what you changed"
`Blissium uses your commit message as the intent for verification.
$3
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
to see what commit message was used:
`bash
blissium verify --debug
`
2. Run with to watch the tests execute:
`bash
blissium verify --headed
`
3. Check the saved test file in to review what was testedTip: Write clear, descriptive commit messages that explain what the change does.
$3
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:
`bash
blissium verify --headed
`
5. Try manual configuration - edit with the correct selectors:
`json
{
"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
)
- Page requires JavaScript to load (increase timeout in code)
- Login requires additional steps (captcha, 2FA) - not currently supportedExamples
$3
`bash
Initialize
cd my-react-app
blissium initSet 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 devVerify changes
blissium verify
`$3
bash
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: test@example.com
? 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 devVerify changes (authentication happens automatically)
blissium verify
`$3
yaml
.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
$3
See detailed information about the verification:
bash
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
$3
Blissium saves all generated tests to
for debugging and review:`bash
.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 (
flag)
- Understand AI's test strategy
- Share tests with team membersCommands:
`bash
List all saved tests
blissium show-testsView specific test
blissium show-tests a1b2c3d4Rerun last test (no API call)
blissium verify --rerunExport test to standalone Playwright file (latest commit)
blissium export-testOr export specific commit
blissium export-test a1b2c3d4
`These files are automatically ignored by git (in
).$3
When a test fails, you can export it to a standalone Playwright test for detailed debugging:
`bash
Export the latest test (or specify commit hash)
blissium export-testSelectively 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/.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
The exported test includes authentication logic automatically if configured.
$3
Blissium can capture videos and screenshots during test execution to help debug failures:
bash
Record video of test execution
blissium verify --videoTake screenshots on test failures
blissium verify --screenshotsCombine both
blissium verify --video --screenshots --headed
`Artifacts are saved to:
- Videos:
- - First test execution
- retry-run.webm - Auto-retry execution (if tests failed and were regenerated)
- Screenshots: .blissium/screenshots/
- 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: or retry-test-1-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
$3
Run basic sanity checks without AI:
bash
blissium verify --mock
`Useful for:
- Testing Blissium itself
- Quick smoke tests without API costs
- Debugging server connectivity issues
$3
If your application requires users to log in before accessing pages, Blissium can automatically handle authentication:
During initialization:
bash
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: test@example.com
? 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
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
:
`json
{
"serverUrl": "http://localhost:3000",
"auth": {
"required": true,
"loginUrl": "/auth/login",
"usernameSelector": "input[name='email']",
"passwordSelector": "input[name='password']",
"submitSelector": "button.login-btn",
"testUsername": "testuser@example.com",
"testPassword": "securepassword123"
}
}
`Security notes:
- Test credentials are stored locally in
- Always add 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:
`json
{
"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.
- MCP server for automatic intent logging
- Test result caching
- Custom test templates
- Integration with existing test frameworks
- Support for pre-commit verification (before committing)
Issues and feature requests: https://github.com/bliss-labs-ai/blissium/issues