# Claude Code
Source: https://docs.polarity.cc/claude-code
Connect Paragon to Claude Code via MCP
Add Paragon as an MCP server in Claude Code to get code review, testing, and analysis tools directly in your terminal.
## Prerequisites
* Active Claude subscription (Pro, Max, or API access)
* [Paragon CLI installed](/paragon/overview)
## Get your API key
1. Go to [app.paragon.run](https://app.paragon.run)
2. Sign in or create an account
3. Navigate to **Settings** → **API Keys**
4. Copy your API key
Some tools like `generate_tests`, `run_paragon`, `list_test_suites`, and `save_to_suite` require an API key. Other tools work without one.
## Setup
```bash theme={null}
npm install -g @anthropic-ai/claude-code
```
Run the following command to register Paragon with Claude Code:
```bash theme={null}
claude mcp add-json paragon '{"command":"paragon","args":["mcp-server"],"env":{"POLARITY_API_KEY":"your-api-key-here"}}'
```
Replace `your-api-key-here` with your API key from [app.paragon.run](https://app.paragon.run).
```bash theme={null}
claude mcp list
```
You should see `paragon` listed as a configured MCP server.
## Available tools
Once connected, Paragon exposes 12 tools to Claude Code:
### Code review
| Tool | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run_paragon` | Run a Paragon AI prompt — reads/writes files, runs shell commands, and performs complex coding tasks. Requires API key. |
| `list_reviewed_prs` | List pull requests with Paragon review comments in the current repository. Supports filtering by state (`open`, `closed`, `all`). |
| `get_review_comments` | Get parsed review findings from a PR, including severity, descriptions, file locations, and suggested fixes. Auto-detects PR from current branch if omitted. |
| `resolve_review_comment` | Reply to a review comment and optionally resolve the thread. |
### Testing
| Tool | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detect_test_framework` | Scan the repository and detect test frameworks in use. Returns framework details, run commands, file patterns, and confidence level. |
| `find_tests` | Discover existing test files using framework-aware file patterns. Returns file paths and count. |
| `run_tests` | Execute unit/integration tests using the detected or specified framework. Returns pass/fail status and full output. |
| `run_e2e_tests` | Run Playwright E2E tests locally. Installs browsers if needed, optionally starts a dev server, and captures results. |
| `generate_tests` | Generate unit, integration, or E2E tests using Paragon AI. Detects patterns, writes tests, verifies compilation, runs them, and fixes failures. Requires API key. |
### Test suite management
| Tool | Description |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `list_test_suites` | List your test repositories and suites from the Paragon cloud dashboard. Requires API key. |
| `save_to_suite` | Save locally generated test files to a Paragon cloud test suite. Requires API key. |
### Utility
| Tool | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `check_setup` | Check if the MCP server is properly configured. Reports the status of the API key, Paragon binary, and GitHub CLI. |
## Usage
After setup, Claude Code can automatically use Paragon tools when relevant. You can also request them directly:
```
> Review the comments on my current PR and fix the issues
> Generate unit tests for src/auth.ts
> Run the test suite and show me what's failing
> Find all Playwright tests and run them in headed mode
```
## Configuration
To update your API key or other environment variables, remove and re-add the server:
```bash theme={null}
claude mcp remove paragon
claude mcp add-json paragon '{"command":"paragon","args":["mcp-server"],"env":{"POLARITY_API_KEY":"your-new-api-key"}}'
```
# Cursor
Source: https://docs.polarity.cc/cursor
Connect Paragon to Cursor via MCP
Add Paragon as an MCP server in Cursor to get code review, testing, and analysis tools directly in your editor.
## Prerequisites
* Cursor editor installed
* [Paragon CLI installed](/paragon/overview)
## Get your API key
1. Go to [app.paragon.run](https://app.paragon.run)
2. Sign in or create an account
3. Navigate to **Settings** → **API Keys**
4. Copy your API key
Some tools like `generate_tests`, `run_paragon`, `list_test_suites`, and `save_to_suite` require an API key. Other tools work without one.
## Setup
Open Cursor and go to **Settings** → **MCP**. Click **+ Add new MCP server**.
Select **Type: command** and add the following configuration:
```json theme={null}
{
"mcpServers": {
"paragon": {
"command": "paragon",
"args": ["mcp-server"],
"env": {
"POLARITY_API_KEY": "your-api-key-here"
}
}
}
}
```
Replace `your-api-key-here` with your API key from [app.paragon.run](https://app.paragon.run).
Alternatively, create a `.cursor/mcp.json` file in your project root with the same configuration.
After saving, you should see **paragon** listed in your MCP servers with a green status indicator.
## Available tools
Once connected, Paragon exposes 12 tools to Cursor:
### Code review
| Tool | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run_paragon` | Run a Paragon AI prompt — reads/writes files, runs shell commands, and performs complex coding tasks. Requires API key. |
| `list_reviewed_prs` | List pull requests with Paragon review comments in the current repository. Supports filtering by state (`open`, `closed`, `all`). |
| `get_review_comments` | Get parsed review findings from a PR, including severity, descriptions, file locations, and suggested fixes. Auto-detects PR from current branch if omitted. |
| `resolve_review_comment` | Reply to a review comment and optionally resolve the thread. |
### Testing
| Tool | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detect_test_framework` | Scan the repository and detect test frameworks in use. Returns framework details, run commands, file patterns, and confidence level. |
| `find_tests` | Discover existing test files using framework-aware file patterns. Returns file paths and count. |
| `run_tests` | Execute unit/integration tests using the detected or specified framework. Returns pass/fail status and full output. |
| `run_e2e_tests` | Run Playwright E2E tests locally. Installs browsers if needed, optionally starts a dev server, and captures results. |
| `generate_tests` | Generate unit, integration, or E2E tests using Paragon AI. Detects patterns, writes tests, verifies compilation, runs them, and fixes failures. Requires API key. |
### Test suite management
| Tool | Description |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `list_test_suites` | List your test repositories and suites from the Paragon cloud dashboard. Requires API key. |
| `save_to_suite` | Save locally generated test files to a Paragon cloud test suite. Requires API key. |
### Utility
| Tool | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `check_setup` | Check if the MCP server is properly configured. Reports the status of the API key, Paragon binary, and GitHub CLI. |
## Usage
After setup, Cursor's agent mode can automatically use Paragon tools when relevant. You can also request them directly in chat:
```
Review the comments on my current PR and fix the issues
Generate unit tests for src/auth.ts
Run the test suite and show me what's failing
Find all Playwright tests and run them in headed mode
```
# Integrations
Source: https://docs.polarity.cc/dashboard/integrations
Connect cloud services, tools, and manage team collaboration using MCP.
## Infrastructure (MCP)
Connect cloud services and tools using the Model Context Protocol (MCP) for enhanced analysis.
### Available Integrations
Connect with IAM access keys to manage S3, EC2, and more
Connect using gcloud CLI authentication
Connect your deployments via OAuth
Connect your project with access token
Connect for issue tracking integration
Connect for project tracking
Connect workspace via OAuth
### Connecting Services
Most integrations use OAuth for secure authentication:
Go to Settings → Infrastructure
Click "Connect" on the service you want
Copy the CLI command and run it in your terminal
Complete the OAuth flow in your browser
Paste the token back into the dashboard
### Custom MCP Servers
Click "Add Custom MCP" to create custom server configurations for your own tools and services. Configure the server type (stdio, http, SSE), command/URL, and environment variables.
## Team Management
Collaborate with your team using pooled credits and shared resources.
**Requirement**: Team features require the Startup plan (\$500/month).
### Team Roles
* Invite and remove members
* Manage billing and seats
* Edit team settings
* Access team credit pool
* View team information
* Leave team
### Inviting Members
1. Click "Invite team member"
2. Enter their email address
3. Invitation email sent with unique link
4. Member accepts and joins team
### Team Capacity
* View current members vs. total capacity
* Track pending invitations
* See available slots
* Monitor team credit usage
# Issues & PR Reviews
Source: https://docs.polarity.cc/dashboard/issues
View and manage all automatically reviewed pull requests and discovered issues.
The Issues page is your central hub for viewing all automatically reviewed pull requests and the issues found.
### PR List
View all PRs that have been automatically reviewed:
| Feature | Description |
| --------------------- | -------------------------------------------- |
| **Search** | Filter PRs by title |
| **Repository Filter** | Show PRs from specific repositories |
| **Sentiment Score** | Color-coded status (Good/Fair/Poor/Critical) |
| **Author** | PR author with avatar |
| **Date** | Relative timestamp (e.g., "5 min ago") |
### Analytics Dashboard
View metrics and trends for your PR reviews:
Total count with run breakdown
Total issues with average per PR
Estimated time saved
Filter by 7, 30, or 90 days
The trend chart visualizes review activity over time.
### Issue Detail View
Click on any PR to view detailed issues found:
* Issues sorted by severity (Critical → High → Medium → Low)
* Issue title and description
* File path and line number
* Code snippet display
* Link to GitHub comment thread
* Resolution status
## Trigger Reviews Manually
You can trigger a PR review on-demand by tagging `@paragon-review` in any comment on a pull request. This is useful when:
* You want to re-run a review after making changes
* The repository doesn't have automatic reviews enabled
* You want a review on a specific PR without enabling auto-reviews
Simply comment `@paragon-review` on any open pull request to trigger an AI-powered code review.
# Alerts
Source: https://docs.polarity.cc/dashboard/monitoring/alerts
Configure notifications for monitor findings and downtime.
Get notified when monitors detect issues or services go down.
## Alert Integrations
Connect your team communication tools to receive alerts.
### Supported Platforms
Send alerts to any email address
Post to a Slack channel via webhook
Post to a Discord channel via webhook
Post to a Teams channel via webhook
### Add an Integration
Navigate to the Alerts settings page
Select your platform
Add a name and webhook URL (or email address)
Click Test to verify the connection
Click Add Integration to save
### Getting Webhook URLs
| Platform | How to Get Webhook URL |
| ----------- | ------------------------------------------------------- |
| **Slack** | Apps → Incoming Webhooks → Add to Slack |
| **Discord** | Server Settings → Integrations → Webhooks → New Webhook |
| **Teams** | Channel → Connectors → Incoming Webhook |
### Managing Integrations
* **Enable/Disable** - Toggle integrations on or off
* **Test** - Send a test message to verify it works
* **Delete** - Remove integrations you no longer need
## Alert Thresholds
Choose which severity levels trigger alerts:
| Severity | Description | Default |
| ------------ | ------------------------------------ | -------- |
| **Critical** | Immediate security threats | Enabled |
| **High** | Important issues requiring attention | Enabled |
| **Medium** | Moderate issues to review | Disabled |
| **Low** | Minor issues and recommendations | Disabled |
Configure thresholds in **Monitoring → Alerts**.
Even with thresholds disabled, all findings still appear in the Findings page—they just won't trigger alerts.
## Uptime Alerts
Uptime monitors can send alerts to specific integrations when URLs go down.
### Configure per Monitor
When creating or editing an uptime monitor:
1. Click the monitor to open settings
2. Select which integrations should receive alerts
3. Save changes
This lets you route different monitors to different channels (e.g., production alerts to PagerDuty, staging alerts to Slack).
## Findings
View all findings from infrastructure monitors in **Monitoring → Findings**.
### Finding Details
Each finding includes:
* **Title** - What was detected
* **Description** - Details about the issue
* **Severity** - Critical, High, Medium, or Low
* **Resource** - Which resource is affected
* **Remediation** - How to fix it
* **Monitor** - Which monitor detected it
### Managing Findings
| Status | Meaning |
| --------------- | --------------- |
| **Open** | Needs attention |
| **In Progress** | Being worked on |
| **Resolved** | Issue fixed |
| **Ignored** | Not applicable |
Click a finding to change its status or view full details.
### Clear Findings
To clear all findings:
1. Go to Monitoring → Findings
2. Click "Clear All"
3. Confirm the action
Clearing findings is permanent and cannot be undone.
## Best Practices
Start with Critical and High alerts enabled. Add Medium alerts once you've addressed the urgent issues.
Use separate Slack channels for different severity levels to avoid alert fatigue.
Test your integrations regularly to ensure webhooks haven't expired.
# Creating Monitors
Source: https://docs.polarity.cc/dashboard/monitoring/creating
Add infrastructure monitors and uptime checks.
The Monitoring page has two tabs: **Infrastructure** for AI-powered scans and **Uptime** for URL health checks.
## Infrastructure Monitors
Infrastructure monitors run AI prompts on a schedule to scan your cloud services, code, and dependencies.
### Create from Template
Navigate to the Monitoring page
Click the "+" button to add a new monitor
Choose from AWS Security, Cost Optimization, Code Quality, etc.
Select Hourly, Daily, or Weekly
Click Create to start the monitor
### Available Templates
| Template | What It Does |
| ---------------------- | --------------------------------------------------------------------- |
| **AWS Security Scan** | Scans for misconfigurations and vulnerabilities in AWS |
| **Exposed S3 Buckets** | Finds publicly accessible S3 buckets |
| **Cost Optimization** | Identifies unused EC2 instances and savings opportunities |
| **Terraform Drift** | Detects differences between Terraform state and actual infrastructure |
| **Code Quality** | Analyzes code for anti-patterns, bugs, and issues |
| **Dependency Scan** | Checks for vulnerable or outdated packages |
| **README Sync** | Keeps README.md updated with codebase changes |
### Custom Prompts
Create a monitor with any prompt:
1. Click "Add Monitor"
2. Select "Custom" instead of a template
3. Write your prompt describing what to check
4. Select cadence and save
Example prompts:
```
Check my Vercel deployments for failed builds
Scan for hardcoded API keys in the codebase
Audit IAM permissions for overly permissive policies
```
### Repository Selection
Some monitors analyze code and require a repository:
* **Code Quality** - requires repository
* **Dependency Scan** - requires repository
* **README Sync** - requires repository
Select the repository from the dropdown when creating these monitors.
### Run Now
To run a monitor immediately instead of waiting for the schedule:
1. Find the monitor in the list
2. Click the refresh icon
3. Results appear in the detail panel
## Uptime Monitors
Uptime monitors check if URLs are responding.
### Create an Uptime Monitor
Switch to the Uptime tab
Click the "+" button
Add name, URL, and check interval
Select which integrations receive alerts
Click Create to start monitoring
### Configuration Options
| Field | Description |
| ---------------------- | ------------------------------------------------ |
| **Name** | Display name for the monitor |
| **URL** | The URL to check (https\:// added automatically) |
| **Interval** | How often to check (30s, 60s, 5min, etc.) |
| **Alert Integrations** | Which channels receive down alerts |
### Check Now
Click the refresh icon on any uptime monitor to run an immediate check. The result shows:
* **Status** - Up or Down
* **Latency** - Response time in milliseconds
## Managing Monitors
### Enable/Disable
Toggle monitors on or off without deleting them. Disabled monitors don't run but keep their configuration.
### Delete
Click the trash icon to permanently remove a monitor.
### View Results
Click any infrastructure monitor to see:
* **Last run time** and duration
* **Output summary** from the AI
* **Findings** with severity levels
* **Full output** in markdown format
## Next Steps
Set up notifications for findings and downtime
# Overview
Source: https://docs.polarity.cc/dashboard/monitoring/overview
Scheduled AI monitors and uptime checks for your infrastructure and services.
Paragon Monitoring provides two types of automated checks: AI-powered infrastructure monitors that scan for security issues and code quality, and uptime monitors that track service availability.
## Monitor Types
AI-powered scheduled scans for security, cost optimization, code quality, and more
URL health checks that track availability and response times
## Infrastructure Monitors
Run AI prompts on a schedule to scan your infrastructure and code:
| Template | Description |
| ---------------------- | ---------------------------------------------- |
| **AWS Security Scan** | Scan for misconfigurations and vulnerabilities |
| **Exposed S3 Buckets** | Find publicly accessible buckets |
| **Cost Optimization** | Identify unused resources and savings |
| **Terraform Drift** | Detect state vs actual config drift |
| **Code Quality** | Check for anti-patterns and issues |
| **Dependency Scan** | Find outdated or vulnerable packages |
| **README Sync** | Keep README updated with codebase changes |
Infrastructure monitors connect to your cloud services via MCP integrations (AWS, GCP, Vercel, Supabase, etc.).
### Cadence Options
| Cadence | When It Runs |
| ---------- | ------------- |
| **Hourly** | Every hour |
| **Daily** | Once per day |
| **Weekly** | Once per week |
## Uptime Monitors
Track whether your URLs are responding:
* Add any URL (websites, APIs, health endpoints)
* Set check interval (30s, 60s, 5min, etc.)
* Get alerted when services go down
* Track response latency over time
### Status Indicators
| Status | Meaning |
| ----------- | -------------------------------------- |
| **Up** | URL responding successfully |
| **Down** | URL not responding or returning errors |
| **Unknown** | Not yet checked |
## Findings
When infrastructure monitors detect issues, they create findings with severity levels:
Immediate security threats requiring urgent action
Important issues requiring attention
Moderate issues to review
Minor issues and recommendations
Findings can be marked as:
* **Open** - Needs attention
* **In Progress** - Being worked on
* **Resolved** - Fixed
* **Ignored** - Not applicable
## Dashboard
The Monitoring dashboard shows:
* **Service Health %** - Percentage of healthy monitors
* **Needs Attention %** - Monitors with issues
* **Active Monitors** - Total monitors running
* **Health trend chart** - Historical view by day/week/month
## Next Steps
Add infrastructure or uptime monitors
Set up notifications for issues
# Setup
Source: https://docs.polarity.cc/dashboard/monitoring/setup
Connect infrastructure services to enable AI-powered monitoring.
Before creating infrastructure monitors, connect the services you want to scan.
## Infrastructure Connections
Infrastructure monitors use MCP (Model Context Protocol) to connect to your cloud services. Connect services in **Settings → Infrastructure**.
## Available Integrations
### Cloud Infrastructure
| Service | Auth Method | What You Need |
| ---------------- | ---------------- | ---------------------------------------------------- |
| **AWS** | Access Keys | Access Key ID, Secret Access Key, Region |
| **GCP** | Service Account | Project ID, Service Account JSON key |
| **Azure** | App Registration | Subscription ID, Tenant ID, Client ID, Client Secret |
| **Cloudflare** | API Token | API Token, Account ID |
| **DigitalOcean** | API Token | Personal Access Token |
| **Fly.io** | API Token | Personal Access Token |
### Frontend & App Platforms
| Service | Auth Method | What You Need |
| ----------- | ----------- | ------------------------------------ |
| **Vercel** | OAuth | Click Connect → authorize in browser |
| **Netlify** | API Token | Personal Access Token |
| **Heroku** | API Key | API Key from account settings |
### Database Providers
| Service | Auth Method | What You Need |
| ------------- | ----------------- | --------------------------------------------- |
| **Supabase** | Access Token | Access Token, Project Reference |
| **MongoDB** | Connection String | MongoDB connection string (mongodb+srv://...) |
| **Firebase** | Project ID | Project ID (requires gcloud CLI auth) |
| **Appwrite** | API Key | Project ID, API Key, Secret |
| **Snowflake** | Credentials | Account Identifier, User, Password |
### Monitoring & Infrastructure
| Service | Auth Method | What You Need |
| ------------------- | ----------- | ------------------------------------ |
| **DataDog** | API Keys | API Key, Application Key, Site |
| **Sentry** | OAuth | Click Connect → authorize in browser |
| **Terraform Cloud** | API Token | API Token, Organization name |
### Work Collaboration
| Service | Auth Method | What You Need |
| ---------- | ----------- | ------------------------------------ |
| **Linear** | OAuth | Click Connect → authorize in browser |
| **Jira** | OAuth | Click Connect → authorize in browser |
| **Notion** | OAuth | Click Connect → authorize in browser |
| **Slack** | Bot Token | Bot User OAuth Token, Team ID |
## Connecting Services
### OAuth Services (Vercel, Sentry, Linear, Jira, Notion)
Click the Connect button on the service
Complete the OAuth flow in your browser
Service appears as connected
### API Key Services (AWS, GCP, Supabase, etc.)
Click the Connect button on the service
Each service shows step-by-step instructions with links
Paste your API keys, tokens, or credentials
Click Save to connect the service
### Example: Connecting AWS
1. Go to [AWS IAM Console](https://console.aws.amazon.com/iam/home#/security_credentials)
2. Click "Create access key" under Access keys section
3. Select "Application running outside AWS"
4. Copy the Access Key ID and Secret Access Key
5. Paste into Paragon and set your region (e.g., `us-east-1`)
### Example: Connecting Supabase
1. Go to [Supabase Access Tokens](https://supabase.com/dashboard/account/tokens)
2. Click "Generate new token"
3. Copy the token
4. Find your Project Ref in your project URL: `supabase.com/dashboard/project/[PROJECT_REF]`
5. Paste both values into Paragon
## Custom MCP Servers
Add your own MCP servers for services not in the list:
1. Click "Add Custom MCP"
2. Enter a name
3. Select protocol type (stdio, http, or sse)
4. Configure command/URL and environment variables
5. Save
## Repository Connection
Some monitors require a connected GitHub repository:
* **Code Quality** - analyzes code in a repo
* **Dependency Scan** - checks package files in a repo
* **README Sync** - updates README.md in a repo
Ensure the Paragon GitHub App is installed and repositories are added in **Settings → Repositories**.
## Disconnecting Services
1. Find the connected service
2. Click the disconnect/remove button
3. Confirm disconnection
Disconnecting a service will cause monitors that depend on it to fail.
## Next Steps
Set up your first infrastructure or uptime monitor
# Overview
Source: https://docs.polarity.cc/dashboard/overview
Your central hub for managing automated PR reviews, viewing code analysis results, and managing your team.
The Paragon Dashboard is your central hub for managing automated PR reviews, viewing code analysis results, configuring infrastructure connections, and managing your team.
The dashboard is organized into the following pages:
* **Home**: Credit balance, statistics, and CLI installation
* **Issues**: View all PR reviews with analytics and filtering
* **Settings**: Configure PR reviews, severity filters, custom rules, and GitHub connection
## Quick Start
Install the CLI globally with npm
Connect your GitHub account in Settings
Enable automatic PR reviews and add repositories
View issues found in the Issues page
Configure severity filters and custom rules
## Installation & Setup
Get started with Paragon by installing the CLI and authenticating with your API key.
### Step 1: Install CLI
```bash theme={null}
npm i -g @polarityinc/paragon
```
### Step 2: Authenticate
```bash theme={null}
paragon auth login
```
### Step 3: Verify Installation
```bash theme={null}
paragon
```
**API Key**: Your API key is available in Settings. Keep it secure and do not share publicly.
## Home
The Home page provides an overview of your account status and quick access to key features.
### Credit Balance & Plan
Your credit balance and current plan are displayed at the top:
* Current credit balance with visual indicator
* Active plan name (Free, Developer, Startup)
* "Add Credits" button for paid plans
### Statistics
Click "Show All Stats" to expand your usage statistics:
* Issues caught by severity (Critical, High, Medium, Low)
* Total tokens used
* Messages sent
* Estimated hours saved
### Install Paragon CLI
Click the install button to open a modal with copy-paste commands for CLI setup.
# Settings
Source: https://docs.polarity.cc/dashboard/settings
Configure your account, PR reviews, severity filters, and custom rules.
Configure your account, PR reviews, and integrations from the Settings page.
### Account
* **Name**: Editable display name
* **Email**: Synced from GitHub (read-only)
* **Avatar**: Synced from GitHub profile
### Automatic PR Reviews
Toggle automatic PR scanning on/off and manage monitored repositories:
1. Enable the "Automatic PR Reviews" toggle
2. Click "Add Repos" to select repositories
3. Search and select repositories with checkboxes
4. Monitored repos appear in the list below
5. Remove repos using the X button
Disabling PR reviews will remove all monitored repositories.
### Review Options
Configure what to include in automatic PR reviews:
Find issues beyond the changed lines. When enabled, Paragon analyzes surrounding code context to catch issues that may be affected by your changes but aren't in the diff itself.
**Example:** You modify a function's return type. Paragon flags callers of that function elsewhere in the file that may now have type mismatches.
One-click commit fixes directly from the PR. Paragon provides actionable code suggestions that you can apply instantly without leaving GitHub.
**Example:** Paragon detects a missing null check and offers a "Commit suggestion" button that adds `if (user == null) return;` with a single click.
Show inline diffs for suggestions. Instead of just describing the fix, Paragon displays a visual before/after diff so you can see exactly what changes are proposed.
**Example:**
```diff theme={null}
- const data = response.data
+ const data = response.data ?? []
```
Generate an overview of review findings at the top of the PR. Provides a high-level summary including issue counts by severity, key concerns, and overall assessment.
**Example:** "This PR adds user authentication. Found 2 high-severity issues (SQL injection risk, missing rate limiting) and 3 medium-severity suggestions."
Split the PR summary and detailed review into 2 separate comments. Useful for large PRs where you want the overview separate from line-by-line feedback.
**Example:** First comment contains the executive summary and issue counts. Second comment contains all inline code review comments.
Review draft pull requests. When enabled, Paragon runs automatic reviews on PRs marked as drafts, giving you early feedback before the PR is ready for human review.
**Example:** You open a draft PR for a new feature. Paragon immediately reviews it and catches a security issue before you've even requested review from teammates.
Generate an architecture flow diagram showing how the changed code fits into the system. Visualizes data flow, component relationships, and integration points.
**Example:** For a PR modifying an API endpoint, Paragon generates a Mermaid diagram showing: Client → API Gateway → Auth Middleware → Your Endpoint → Database.
### GitHub Connection
Connect your GitHub account to enable repository access:
* View connection status in "Code Host Connections"
* Click "Connect" or "Reconnect" to authorize
* Tokens are encrypted and auto-refresh
### API Key
Your API key is displayed in Settings. Use it for CLI authentication with `paragon auth login`.
## Severity Filters
Control which types of issues are reported in your PR reviews.
### Issue Severity Levels
Security vulnerabilities, data loss risks, crash-causing bugs
Major bugs, significant performance issues
Code quality issues, best practice violations
Style issues, minor improvements, suggestions
### Additional Filters
| Filter | Description |
| ------------------ | --------------------------------------------------------- |
| **Out of Diff** | Include issues found outside the changed lines |
| **PR Summary** | Generate a summary of analysis findings |
| **System Diagram** | Generate architecture visualization (requires PR Summary) |
At least one severity filter must remain enabled.
## Custom Rules
Define custom coding standards for the AI to follow during code reviews.
### Upload Documents
Upload existing documentation to automatically extract rules:
* **Supported formats**: PDF, DOCX, MD, TXT
* AI extracts coding rules automatically
* Rules tagged with "upload" source
### Manual Entry
Add rules by typing directly:
1. Click "Manual Entry"
2. Type your rule or guideline
3. Save to add to active rules
### Example Rules
```
All API endpoints must include error handling with try-catch
Use TypeScript strict mode for all new files
Database queries must use parameterized statements
```
### Managing Rules
* Click any rule to view full content
* Copy rule content to clipboard
* Delete rules no longer needed
* View source (upload/manual) and creation date
# Analytics & More
Source: https://docs.polarity.cc/dashboard/testing/analytics
Track test performance, pass rates, scheduling, and notifications.
The analytics dashboard gives you visibility into your testing health across all repositories.
## Dashboard Stats
The main testing dashboard shows four key metrics:
| Metric | Description |
| --------------- | ----------------------------------------- |
| **Total Tests** | Number of tests across all repositories |
| **Pass Rate** | Percentage of tests passing |
| **Hours Saved** | Estimated manual testing time saved |
| **Flaky Tests** | Tests that pass sometimes, fail sometimes |
## Repository Health
The health visualization shows each repository as a bar:
```
my-frontend ████████████░░░░ 75% passing
my-backend ████████████████ 100% passing
my-api ████░░░░░░░░░░░░ 25% passing
```
* **Green** = Passing tests
* **Red** = Failing tests
* **Gray** = Tests not run
Click any repository to drill down into its test details.
## Pass Rate Trends
Track how your pass rate changes over time:
* Daily pass rate percentage
* Week-over-week comparison
* Identify when regressions were introduced
***
## Flaky Test Detection
A test is marked **flaky** when it:
* Passes on some runs, fails on others
* Has inconsistent results without code changes
### Why Flaky Tests Matter
Flaky tests:
* Waste time investigating false failures
* Reduce trust in your test suite
* Slow down development
### Fixing Flaky Tests
| Cause | Solution |
| ---------------- | ------------------------------- |
| Race conditions | Add explicit waits |
| Shared state | Isolate test data |
| Network timing | Mock external APIs |
| Animation timing | Wait for animations to complete |
| Random data | Use deterministic test data |
***
## Test Duration
See which tests are slow:
* Average duration per test
* Duration trends over time
* Identify tests that have gotten slower
Slow tests increase feedback time and CI costs.
***
## Run History
View aggregated statistics:
* Total runs this week/month
* Runs by trigger type (Manual, Scheduled, PR, Push)
* Runs by platform (Chrome, Firefox, Safari)
***
## Filtering Analytics
Filter analytics by:
* **Repository** - Focus on one repo
* **Time range** - Last 7 days, 30 days, 90 days
* **Test type** - Unit, Integration, E2E, Performance
***
## Exporting Data
Export analytics for reporting:
1. Go to **Testing > Analytics**
2. Set your filters
3. Click **Export**
4. Download as CSV
***
## Notifications
Get notified when tests complete.
### Enable Notifications
Go to **Settings > Alerts** and configure:
| Notification | When It Fires |
| ------------------ | -------------------------- |
| **On Failure** | Any test fails |
| **On Flaky** | A test is marked flaky |
| **On Success** | All tests pass (optional) |
| **Suite Complete** | All scheduled tests finish |
### Notification Channels
| Channel | Description |
| ------------------- | --------------------------------------------- |
| **Email** | Send alerts directly to any email address |
| **Slack** | Post to a Slack channel via incoming webhook |
| **Discord** | Post to a Discord channel via webhook |
| **Microsoft Teams** | Post to a Teams channel via connector webhook |
### Setting Up Integrations
Navigate to the alert settings page
Select your preferred platform
Paste your webhook URL (or enter email address)
Click "Test" to verify it works
You can add multiple integrations. For example, send critical failures to Slack and a summary email to the team lead.
***
## Best Practices
Review flaky tests weekly. A few flaky tests can erode trust in your entire suite.
Watch for pass rate drops after deployments—they indicate regressions.
Keep E2E tests under 30 seconds when possible. Long tests are more likely to be flaky.
Schedule tests during off-peak hours to avoid impacting staging environments.
Don't schedule destructive tests against production if they create test data or modify state.
# Evolving Tests
Source: https://docs.polarity.cc/dashboard/testing/evolving
Automatically update tests when your code changes.
Evolving Tests keeps your test suite in sync with your code. When you make changes, Paragon analyzes the PR and proposes test additions, updates, or removals.
## How It Works
```
Code changes in PR → Paragon analyzes impact → Proposes test changes → You review and accept
```
Make code changes and open a pull request
AI analyzes your changes and existing tests
Paragon posts a GitHub comment with proposed test changes
Review proposals in the dashboard
Accept to apply changes, reject to ignore
***
## Enable Evolving Tests
Navigate to your repositories
Select the repository to configure
Scroll to the Evolving Tests settings
Turn on "Enable Evolving Tests"
Set auto-run, open access, and excluded branches
Save your settings
***
## Configuration Options
### Auto-Run on PR
| Setting | Behavior |
| ------------ | ----------------------------------------------- |
| **Enabled** | Paragon automatically analyzes every PR |
| **Disabled** | Manually trigger with `@paragon-evolve` comment |
When disabled, comment `@paragon-evolve` on any PR to trigger analysis.
### Open Access
Allow external contributors (outside your organization) to trigger `@paragon-evolve` on their PRs.
Only enable for public repositories where you trust community contributions.
### Include Draft PRs
By default, evolving tests only run on non-draft PRs. Enable this to also analyze draft PRs.
### Excluded Branches
Skip evolving tests for certain branches. Supports wildcards:
```
main
develop
release/*
hotfix/*
dependabot/*
```
Use cases:
* Skip main branch (no PR to a branch you're already on)
* Skip release branches (tests should be stable)
* Skip automated dependency updates
***
## Proposal Types
Paragon proposes three types of changes:
### Add New Tests
When you add new code that isn't covered by tests:
```markdown theme={null}
### New Tests Proposed
**Add test for `calculateShipping` function**
- Reason: New function added with no test coverage
- Confidence: 95%
- Tests:
- Returns $5 for orders under $25
- Returns $0 for orders over $25 (free shipping)
- Handles international addresses with higher rate
```
### Update Existing Tests
When code changes affect existing tests:
```markdown theme={null}
### Test Updates Proposed
**Update test for `calculateDiscount` function**
- Reason: Function signature changed, added `memberType` parameter
- Confidence: 88%
- Changes:
- Add test cases for "gold" member type (30% discount)
- Add test cases for "silver" member type (20% discount)
- Update existing tests to include memberType parameter
```
### Remove Obsolete Tests
When code is removed and tests are no longer needed:
```markdown theme={null}
### Tests to Remove
**Remove test for `legacyCalculator` function**
- Reason: Function deleted in this PR
- Confidence: 100%
```
***
## Reviewing Proposals
### GitHub Comment
When Paragon analyzes a PR, it posts a comment:
```markdown theme={null}
## 🧪 Evolving Tests Analysis
I analyzed your changes and have **3 proposals**:
| Type | Test | Confidence |
|------|------|------------|
| ➕ Add | calculateShipping tests | 95% |
| ✏️ Update | calculateDiscount tests | 88% |
| 🗑️ Remove | legacyCalculator tests | 100% |
[Review proposals →](https://home.polarity.cc/testing/proposals/abc123)
```
### Dashboard Review
Go to **Testing > Proposals** to see all pending proposals:
1. **Filter by repository** - Focus on one repo
2. **Filter by type** - Added, Updated, Removed
3. **Preview changes** - See proposed code inline
4. **View analysis** - Understand why changes are proposed
### Proposal Details
Click any proposal to see:
* **Analysis Summary**: Why Paragon thinks this change is needed
* **Confidence Score**: How certain Paragon is (0-100%)
* **Proposed Code**: The actual test code to be added/updated
* **Affected Files**: Which test files will change
***
## Accepting Proposals
### Accept Single Proposal
1. Click the proposal
2. Review the changes
3. Click **"Accept"**
4. Choose: Push to PR or create new PR
### Accept All Proposals
1. Go to **Testing > Proposals**
2. Select proposals with checkboxes
3. Click **"Accept Selected"**
### What Happens on Accept
When you accept a proposal:
1. Paragon generates the test code
2. Commits to the PR branch (or creates new PR)
3. Posts a GitHub comment confirming changes
4. Proposal marked as accepted
```markdown theme={null}
## ✅ Tests Updated
Applied 3 test changes:
- Added `calculateShipping.test.ts`
- Updated `calculateDiscount.test.ts`
- Removed `legacyCalculator.test.ts`
[View commit →](https://github.com/org/repo/commit/abc123)
```
***
## Rejecting Proposals
### Reject Single Proposal
1. Click the proposal
2. Click **"Reject"**
3. (Optional) Add reason
Rejected proposals won't be proposed again for this PR.
### When to Reject
* **False positive**: Paragon misunderstood the change
* **Already covered**: Existing tests cover this case
* **Not needed**: Intentionally not testing this code
* **Low confidence**: Proposal doesn't look right
***
## Best Practices
### Start with Auto-Run Disabled
When first enabling evolving tests:
1. Disable auto-run initially
2. Manually trigger on a few PRs with `@paragon-evolve`
3. Review proposal quality
4. Enable auto-run once satisfied
### Review Before Accepting
Always review proposals before accepting:
* Check the generated test code makes sense
* Verify assertions match expected behavior
* Ensure test follows your conventions
### Exclude Noisy Branches
Add patterns for branches that don't need test evolution:
```
dependabot/*
renovate/*
*.md-only
```
### Trust Confidence Scores
| Confidence | Meaning |
| ---------- | ---------------------------------------- |
| 90%+ | Highly confident, likely accurate |
| 70-90% | Good confidence, review recommended |
| 50-70% | Medium confidence, careful review needed |
| Below 50% | Low confidence, skeptical review |
***
## Troubleshooting
### Proposals Not Appearing
1. **Check evolving tests is enabled** in repository settings
2. **Check auto-run setting** - if disabled, use `@paragon-evolve`
3. **Check excluded branches** - branch might be excluded
4. **Check draft PR setting** - draft PRs off by default
### Low Quality Proposals
* Make your PR description detailed
* Include context about what changed and why
* Link to related issues
### Too Many Proposals
* Add excluded branches for automated PRs
* Adjust test type filters in settings
* Review and reject false positives (Paragon learns)
## Next Steps
Track test performance and pass rates
# Generating Tests
Source: https://docs.polarity.cc/dashboard/testing/generating
Create tests with AI using the E2E Builder or code generation.
Paragon generates tests using AI. Describe what you want to test, and Paragon writes the code. There are two ways to generate tests depending on the type.
## Test Generation Methods
| Test Type | Method | What It Creates |
| --------------- | ------------- | ----------------------------- |
| **E2E Tests** | E2E Builder | Step-based browser tests |
| **Code Tests** | AI Agent | Unit/integration test files |
| **Performance** | Inline Config | Performance test with budgets |
***
## E2E Builder (Step-Based Tests)
The E2E Builder creates browser-based tests that run against your deployed application.
### Creating an E2E Test
Navigate to the Tests page
Click "New Test" button
Choose the repository for this test
Select "E2E" as the test type
You're redirected to the visual builder
### Building Steps
The E2E Builder provides a visual interface to create test flows:
#### Navigation Steps
| Step | Description | Example |
| -------------- | ------------------- | ------------------------- |
| **Navigate** | Go to a URL | `https://myapp.com/login` |
| **Refresh** | Reload current page | — |
| **New Tab** | Open URL in new tab | — |
| **Switch Tab** | Switch between tabs | — |
#### Interaction Steps
| Step | Description | Example |
| ----------------- | ---------------------- | ---------------------- |
| **Click** | Click an element | Button, link, checkbox |
| **Type** | Enter text in input | Form fields |
| **Select** | Choose dropdown option | Select menus |
| **Hover** | Hover over element | Dropdown triggers |
| **Scroll** | Scroll to element | Lazy-loaded content |
| **Drag and Drop** | Drag element | Kanban boards |
| **File Upload** | Upload file | File inputs |
#### AI Steps
Use natural language for complex interactions:
| Step | Description | Example |
| ------------------- | ------------------ | ---------------------------------------------- |
| **Paragon Action** | AI performs action | "Fill in the login form with test credentials" |
| **Paragon Check** | AI verifies state | "Verify the user is logged in" |
| **Paragon Extract** | AI extracts data | "Get the order ID from the confirmation" |
AI steps are powerful for complex flows. Instead of specifying exact selectors, describe what you want in plain English.
#### Assertion Steps
| Step | Description | Example |
| ----------------- | --------------------- | --------------------------- |
| **Wait** | Wait for time/element | Wait 2 seconds |
| **Wait for URL** | Wait for navigation | `/dashboard` appears in URL |
| **Element Check** | Verify element state | Button is visible/enabled |
| **Page Check** | Verify page content | Text appears on page |
#### Data Steps
| Step | Description | Example |
| ----------------- | ------------------ | ------------- |
| **Set Cookie** | Inject cookie | Auth cookies |
| **Local Storage** | Set localStorage | Feature flags |
| **Set Header** | Add request header | Auth tokens |
### Authentication in E2E Tests
If your tests need to access protected pages, you can record your login flow directly in the E2E builder.
#### Setting Up Auth
In the E2E builder:
1. Click the **key icon** to start recording authentication
2. Log in to your app in the browser
3. Paragon captures your auth session
4. Save your test - the auth is saved with it
Future test runs will use the captured session to authenticate automatically.
Use a dedicated test account when recording authentication.
### Running E2E Tests
E2E tests run against your deployed application (production, staging, or preview URL).
E2E tests **cannot** run on PR events because there's no deployed app yet. They run:
* **Manually**: Click run button
* **On Schedule**: Daily, weekly, custom
* **On Push**: After merge to production (if base URL is production)
### E2E Test Results
After running, view:
* **Step-by-step breakdown**: Each step with pass/fail and duration
* **Screenshots**: Captured at each step
* **Video recording**: Full test playback
* **Console logs**: Browser console output
* **Network requests**: API calls made during test
* **Accessibility violations**: WCAG issues detected
***
## Code Test Generation (Unit & Integration)
Generate unit and integration tests that live in your repository.
### Creating Code Tests
Navigate to the Tests page
Click "New Test" button
Choose the repository for this test
Select the test type
Switch to "Generate New" tab
You're redirected to the AI agent
Tell the agent what to test in natural language
Agent creates the test file
Save directly or create a PR with the test
### Writing Good Prompts
The better your prompt, the better the generated test.
#### Unit Test Prompts
Be specific about the function and expected behavior:
```text theme={null}
Test the calculateDiscount function:
- Returns 0 for orders under $50
- Returns 10% off for orders $50-$100
- Returns 20% off for orders over $100
- Throws error for negative amounts
```
#### Integration Test Prompts
Specify the endpoint, inputs, and expected outputs:
```text theme={null}
Test POST /api/users/register:
- Returns 201 and user object for valid email/password
- Returns 400 for invalid email format
- Returns 409 if email already exists
- Password is not included in response
```
### Supported Frameworks
Paragon generates tests in your preferred framework:
| Language | Frameworks |
| ------------------------- | -------------------- |
| **JavaScript/TypeScript** | vitest, jest, mocha |
| **Python** | pytest, unittest |
| **Go** | go test |
| **Rust** | cargo test |
| **Ruby** | rspec, minitest |
| **Java** | junit, testng |
| **C#** | xunit, nunit, mstest |
| **C++** | gtest, catch2, ctest |
Framework is detected from your project config or can be manually specified.
### Code Test Results
After running, view:
* **Test output**: Standard framework output
* **Assertion results**: Each assertion with pass/fail
* **Coverage** (if enabled): Lines covered by test
* **Duration**: Time to run each test
***
## Performance Tests
Create tests that measure page load performance.
### Creating Performance Tests
Navigate to the Tests page
Click "New Test" button
Choose the repository
Select "Performance" test type
Enter pages to test
Configure performance thresholds
Set network and CPU throttling
Execute the performance test
### Performance Budgets
Set thresholds for key metrics:
| Metric | Description | Good Target |
| -------- | ------------------------ | ----------- |
| **LCP** | Largest Contentful Paint | \< 2.5s |
| **FCP** | First Contentful Paint | \< 1.8s |
| **CLS** | Cumulative Layout Shift | \< 0.1 |
| **TTFB** | Time to First Byte | \< 0.8s |
### Test Conditions
Simulate real-world conditions:
**Network Throttling:**
* 4G (typical mobile)
* Fast 3G
* Slow 3G
* No throttling
**CPU Throttling:**
* No throttle
* 2x slowdown
* 4x slowdown
* 6x slowdown
**Iterations:**
* Run 1-10 times for consistent results
***
## Test Organization
### Suites
Tests are organized into suites (folders):
```
Repository: my-app
├── Suite: Authentication
│ ├── Test: Login flow (E2E)
│ ├── Test: Registration (E2E)
│ └── Test: validateEmail (Unit)
├── Suite: API
│ ├── Test: GET /users (Integration)
│ └── Test: POST /orders (Integration)
└── Suite: Performance
└── Test: Homepage load
```
When creating a test:
* Add to an existing suite
* Create a new suite
### Editing Tests
Click any test to:
* Update name or description
* Regenerate code with new prompt
* Move to different suite
* Delete test
## Next Steps
Learn how tests run on PRs and pushes
# Importing Tests
Source: https://docs.polarity.cc/dashboard/testing/importing
Import existing tests from your repository into Paragon.
Already have tests in your repository? Import them into Paragon to track results, run automatically on PRs, and enable evolving tests.
## Why Import Tests?
When you import existing tests:
* **Track Results**: See pass/fail status in the Paragon dashboard
* **Automate Runs**: Tests run automatically on PRs and pushes
* **Enable Evolving**: Paragon can propose updates when code changes
* **Unified View**: See all test results in one place
Importing tests doesn't copy code into Paragon. Tests remain in your repository and run using your existing framework.
## How to Import
Navigate to the Tests page
Click "New Test" button
Choose the repository containing your tests
Select "Unit" or "Integration" test type
Switch to the "Import Existing" tab
Paragon scans your repo and lists all detected tests
Check the tests you want to import (supports multi-select)
Click "Import Selected" to add tests to your dashboard
## Supported Frameworks
Paragon detects tests based on your project configuration:
### JavaScript/TypeScript
| Framework | Config Files | Test Patterns |
| -------------- | ---------------------- | -------------------------- |
| **Vitest** | `vitest.config.ts` | `*.test.ts`, `*.spec.ts` |
| **Jest** | `jest.config.js` | `*.test.js`, `__tests__/*` |
| **Mocha** | `.mocharc.js` | `test/*.js` |
| **Playwright** | `playwright.config.ts` | `*.spec.ts` |
### Python
| Framework | Config Files | Test Patterns |
| ------------ | ------------------------------ | ------------------------ |
| **Pytest** | `pytest.ini`, `pyproject.toml` | `test_*.py`, `*_test.py` |
| **Unittest** | — | `test_*.py` |
### Other Languages
| Language | Framework | Test Patterns |
| -------- | -------------------- | ------------------------ |
| **Go** | go test | `*_test.go` |
| **Rust** | cargo test | `tests/*.rs`, `#[test]` |
| **Ruby** | RSpec, Minitest | `spec/*.rb`, `test/*.rb` |
| **Java** | JUnit, TestNG | `*Test.java` |
| **C#** | xUnit, NUnit, MSTest | `*Tests.cs` |
| **C++** | GTest, Catch2 | `*_test.cpp` |
## Organizing Imported Tests
### Suites
Tests are organized into suites (folders). When importing:
* Add to an existing suite
* Create a new suite
### Test Types
| Detected As | Mode | Behavior |
| ---------------- | ---------- | ----------------------- |
| Unit test | Code-based | Runs via test framework |
| Integration test | Code-based | Runs via test framework |
| E2E test | Step-based | Runs in browser |
## After Importing
Once imported, your tests appear in the Tests list with:
* **File Path**: Location in your repository
* **Framework**: Detected test framework
* **Test Names**: Individual test cases extracted from the file
* **Status**: Pass/fail from last run
### Run Imported Tests
Click the play button next to any test to run it immediately, or:
* **Run All**: Execute all tests in a suite
* **Run on PR**: Tests run automatically when PRs are opened
* **Schedule**: Set up recurring test runs
### Edit Test Settings
Click any test to:
* Move to a different suite
* Update the framework if needed
* Configure which triggers run this test
## Troubleshooting
### Tests Not Detected
If your tests aren't found:
1. **Check framework config**: Ensure your config file is in the repo root
2. **Check test patterns**: Tests must follow framework conventions
3. **Check file location**: Tests should be in expected directories
### Wrong Framework Detected
You can manually override the detected framework:
1. Click on the imported test
2. Change the framework in settings
3. Save changes
### Missing Test Cases
If individual test cases aren't listed:
* Paragon extracts test names from `describe`/`it` blocks
* Deeply nested tests may show as a single entry
* Run the test to see full breakdown
## Next Steps
Create new tests with AI
# Overview
Source: https://docs.polarity.cc/dashboard/testing/overview
AI-powered test generation, execution, and evolution for your repositories.
Paragon Testing lets you generate, run, and evolve tests for your repositories. Import existing tests, generate new ones with AI, and let Paragon automatically propose test updates when your code changes.
## How It Works
```
Add a repository → Import or generate tests → Tests run automatically → Evolve tests keep them updated
```
Connect a GitHub repository and configure test settings
Import existing tests or generate new ones with AI
Execute manually, on schedule, or automatically on PR/push
Paragon proposes test updates when your code changes
## Test Types
Paragon supports two modes of testing:
### Code Tests (Unit & Integration)
Tests that live in your repository and run via your test framework.
* **Unit Tests**: Test individual functions or components in isolation
* **Integration Tests**: Test multiple parts working together (APIs, databases)
* **Frameworks**: vitest, jest, mocha, pytest, go test, cargo test, and more
Code tests can run automatically on PRs and pushes.
### E2E Tests (Step-Based)
Browser-based tests that run against a deployed URL.
* **Step-Based Builder**: Visual interface to create test flows
* **AI Actions**: Natural language steps like "fill in the login form"
* **Multi-Platform**: Chrome, Firefox, Safari, Mobile
E2E tests run against your production or staging URL.
### Performance Tests
Measure page load speed and Core Web Vitals.
* **Metrics**: LCP, FCP, CLS, TTFB
* **Budgets**: Set thresholds and get alerts when exceeded
* **Conditions**: Test under various network and CPU throttling
## Key Features
| Feature | Description |
| ------------------------ | ------------------------------------------------- |
| **Test Runner** | Run code tests on PR/push, E2E tests on prod URLs |
| **Evolving Tests** | Auto-propose test updates when code changes |
| **Multi-Platform** | Run E2E tests across browsers and devices |
| **Regression Detection** | Automatically flag tests that start failing |
| **GitHub Integration** | Results on PRs, blocking status checks |
## Next Steps
Get tests running on PRs in 5 minutes
Create tests with AI
# Quickstart
Source: https://docs.polarity.cc/dashboard/testing/quickstart
Get tests running on your PRs in 5 minutes.
Get your existing tests running automatically on every PR, with AI-powered test evolution.
## Step 1: Add Your Repository
Open the Testing section in the dashboard
Select your repository from GitHub
Use default settings for now - you can configure later
## Step 2: Import Your Tests
Navigate to the Tests page
Click "New Test" button
Choose the repo you just added
Select your test type
Switch to "Import Existing"
Paragon finds your tests - select the ones you want
Click "Import Selected"
## Step 3: Enable Run on PR
Back to your repositories
Open repository settings
Toggle on "Run on PR"
Your tests now run on every pull request
## Step 4: Enable Evolving Tests
In the same repository settings page
Turn on "Enable Evolving Tests"
Toggle on to auto-analyze every PR
Paragon will now propose test updates when your code changes
***
## What Happens Next
**On your next PR:**
1. Your imported tests run automatically
2. Results appear as a GitHub status check
3. Paragon analyzes your changes and proposes test updates
4. Review proposals and accept to keep tests in sync
***
## Next Steps
Create E2E or unit tests with AI
Fine-tune triggers, env vars, and more
# Adding Repositories
Source: https://docs.polarity.cc/dashboard/testing/repos
Connect GitHub repositories and configure test settings.
Before you can run tests, you need to add a repository and configure its settings.
## Add a Repository
Navigate to the Testing section and click "Repos"
Click the "Add Repository" button
Choose a repository from your connected GitHub account
Set up test runner and environment variables
Click "Add Repository" to finish
## Repository Settings
### AI Model
Select which AI model to use for test generation:
| Model | Description | Usage |
| ---------------- | ----------------------------- | ------------------ |
| **Paragon Fast** | Quick responses, lower cost | Simple tests |
| **Paragon MD** | Balanced performance and cost | Most use cases |
| **Paragon Max** | Maximum capability | Complex test logic |
### Base URL
The URL where your app runs. Required for E2E tests.
```
https://staging.myapp.com
https://myapp.vercel.app
http://localhost:3000
```
### App Path (Monorepos)
If your app is in a subdirectory, specify the path:
```
apps/web
packages/frontend
```
***
## Test Runner Settings
Configure how and when tests run automatically.
### Run on PR
When enabled, code tests run automatically when:
* A new pull request is opened
* New commits are pushed to a PR
* A PR is reopened
Results appear as a GitHub check on the PR.
### Run on Push to Production
When enabled, tests run when code is pushed or merged to your production branch.
1. Enable the toggle
2. Select your production branch (main, master, etc.)
### Open Access
Allow external contributors (outside your organization) to trigger test runs on their PRs.
Only enable this for public repositories where you want community contributors to run tests.
### Per-Suite Triggers
Control which test suites run on PR vs push:
| Suite | Run on PR | Run on Push |
| ----------- | --------- | ----------- |
| Auth Tests | ✓ | ✓ |
| API Tests | ✓ | ✓ |
| Performance | ✗ | ✓ |
This lets you run fast tests on every PR while reserving slower tests for post-merge.
**E2E tests** (step-based) cannot run on PR events because there's no deployed app to test against. They can only run manually, on schedule, or on push when targeting a production URL.
***
## Environment Variables
Add secrets your tests need. Variables are encrypted and only decrypted at runtime.
### Adding Variables
1. Click "Add Variable"
2. Enter the key name and value
3. Paragon auto-detects secrets (names containing "key", "token", "password", etc.)
### Bulk Import
Paste your `.env` file contents to import multiple variables at once:
```
API_KEY=sk-abc123
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=secretpassword
DATABASE_URL=postgres://...
```
Never commit secrets to your repository. Use environment variables instead.
***
## Evolving Tests Settings
Configure automatic test updates when code changes. See [Evolving Tests](/dashboard/testing/evolving) for full documentation.
### Enable Evolving Tests
Toggle to enable the evolve feature for this repository.
### Auto-Run on PR
When enabled, Paragon automatically analyzes PRs and proposes test updates. When disabled, manually trigger with `@paragon-evolve` comment.
### Open Access
Allow external contributors to trigger `@paragon-evolve` on their PRs.
### Include Draft PRs
Run evolve analysis on draft PRs (disabled by default).
### Excluded Branches
Branches where evolving tests won't run. Supports wildcards:
```
main
develop
release/*
hotfix/*
```
***
## Managing Repositories
### Edit Settings
Click on any repository to update its settings.
### Remove Repository
Click the delete button to remove a repository. This removes all tests and run history.
Removing a repository from Testing does not affect your actual GitHub repository.
## Next Steps
Import existing tests from your repository
# Test Runner
Source: https://docs.polarity.cc/dashboard/testing/runner
Run tests manually, on PRs, on push, or on schedule.
Paragon runs tests in different ways depending on the test type. Code tests run on PRs and pushes, while E2E tests run against your deployed URLs.
## How Tests Run
| Test Type | On PR | On Push | Manual | Scheduled |
| --------------------------------- | ----- | ------- | ------ | --------- |
| **Code Tests** (Unit/Integration) | ✓ | ✓ | ✓ | ✓ |
| **E2E Tests** (Step-Based) | ✗ | ✓\* | ✓ | ✓ |
| **Performance Tests** | ✗ | ✓\* | ✓ | ✓ |
\*E2E and Performance tests only run on push if they have a deployed URL to test against.
**Why can't E2E tests run on PRs?** PRs don't have a deployed app yet. E2E tests need a running application to interact with. Use code tests for PR validation, and schedule E2E tests against staging/production.
***
## Running Tests Manually
### Run a Single Test
1. Go to **Testing > Tests**
2. Find your test
3. Click the **play button** next to it
### Run All Tests in a Suite
1. Go to **Testing > Tests**
2. Find the suite
3. Click **"Run All"** on the suite header
### Run All Tests in a Repository
1. Go to **Testing > Repos**
2. Find the repository
3. Click **"Run All Tests"**
***
## Running Tests on PRs
Code tests can run automatically when pull requests are opened or updated.
### Enable PR Testing
1. Go to **Testing > Repos**
2. Click on your repository
3. Enable **"Run on PR"** toggle
4. (Optional) Configure per-suite triggers
### What Triggers PR Tests
Tests run when:
* A new pull request is opened
* New commits are pushed to an existing PR
* A PR is reopened after being closed
### GitHub Integration
When tests run on a PR:
**Status Check:**
```
✓ Paragon Tests — All 12 tests passed
```
or
```
✗ Paragon Tests — 2 of 12 tests failed
```
Click "Details" to see:
* Which tests failed
* Error messages
* Link to full results
**PR Comment (Optional):**
```markdown theme={null}
## Test Results
✓ 10 passed
✗ 2 failed
### Failures
- calculateDiscount: Expected 80, got 100
- POST /api/users: Returned 500 instead of 201
[View full results →](https://home.polarity.cc/testing/runs/abc123)
```
### Block Merges on Failure
Configure Paragon as a required status check:
Settings > Branches > Branch protection rules
Click "Edit" on the main/master protection rule
Check "Require status checks to pass before merging"
Search for "Paragon Tests" and select it
Click "Save changes"
### Open Access for External Contributors
By default, only org members can trigger test runs. Enable **Open Access** in repository settings to allow external contributors to run tests on their PRs.
Only enable Open Access for public repositories where you trust community contributions.
***
## Running Tests on Push
Run tests when code is pushed or merged to your production branch.
### Enable Push Testing
1. Go to **Testing > Repos**
2. Click on your repository
3. Enable **"Run on Push to Production"** toggle
4. Select your production branch (main, master, etc.)
### What Triggers Push Tests
Tests run when:
* Code is pushed directly to the production branch
* A PR is merged into the production branch
### Use Cases
* **Verify merged code**: Catch issues that slip through PRs
* **Run E2E tests**: E2E tests run after merge when there's a deployed app
* **Run performance tests**: Check performance after deployments
***
## Scheduling Tests
Run tests automatically on a recurring schedule.
### Create a Schedule
Navigate to the calendar view
Click "Add Schedule" button
Choose tests, suites, or all tests
Choose daily, weekly, or custom (cron)
Click "Create Schedule"
### Frequency Options
| Option | Example |
| ----------------- | ----------------------------- |
| **Daily** | Every day at 2:00 AM |
| **Weekly** | Every Monday and Friday |
| **Custom (Cron)** | `0 */6 * * *` (every 6 hours) |
### Common Schedules
```
Daily at midnight: 0 0 * * *
Daily at 6 AM: 0 6 * * *
Every Monday 9 AM: 0 9 * * 1
Weekdays at 8 AM: 0 8 * * 1-5
Every 6 hours: 0 */6 * * *
```
### Best Practices
| Test Type | Recommended Schedule |
| ------------------ | -------------------- |
| Smoke tests | Every 6 hours |
| Full suite | Daily (overnight) |
| Critical E2E flows | Every hour |
| Performance tests | Weekly |
Schedule tests during off-peak hours to avoid impacting staging environments.
***
## Viewing Test Results
### Test List
The test list shows status at a glance:
| Status | Meaning |
| -------------- | --------------------------------- |
| 🟢 **Passed** | All assertions succeeded |
| 🔴 **Failed** | One or more assertions failed |
| 🔵 **Running** | Test is currently executing |
| ⚪ **Not Run** | Test hasn't been executed yet |
| 🟡 **Flaky** | Passes sometimes, fails sometimes |
### Run Details
Click on any test run to see:
#### Code Tests
```
✓ calculateDiscount returns 0 for orders under $50
✓ calculateDiscount returns 10% for $50-$100
✗ calculateDiscount returns 20% for over $100
└─ Expected: 80, Received: 100
✓ calculateDiscount throws for negative amounts
```
#### E2E Tests
```
✓ Navigate to https://myapp.com/login (1.2s)
✓ Type "test@example.com" into #email (0.3s)
✓ Type "password123" into #password (0.2s)
✓ Click "Sign In" button (0.1s)
✓ Wait for /dashboard URL (2.1s)
✗ Check "Welcome" text appears (0.5s)
└─ Error: Expected "Welcome" but found "Error: Invalid credentials"
```
Plus for E2E tests:
* **Screenshots**: Visual snapshots at each step
* **Video recording**: Full execution replay
* **Console logs**: Browser console output
* **Network requests**: API calls made
### Test Run History
Go to **Testing > Runs** to see all past runs.
**Filters:**
* Status: Passed, Failed, Running
* Trigger: Manual, Scheduled, Pull Request, Push
* Repository: Filter by repo
* Search: Find by test name
### Multi-Platform Results
E2E tests running on multiple platforms show grouped results:
```
Login Flow Chrome ✓ Firefox ✓ Safari ✗
├─ Chrome Passed (4.2s)
├─ Firefox Passed (5.1s)
└─ Safari Failed (3.8s)
```
***
## Regression Detection
Paragon automatically compares each run to previous runs. If a test that previously passed now fails, it's flagged as a **regression**.
This happens automatically—no configuration needed. Regressions appear highlighted in the runs list.
***
## Notifications
Get notified when tests complete.
### Configure Notifications
Go to **Settings > Alerts**:
| Notification | When |
| -------------- | -------------------------- |
| On Failure | Any test fails |
| On Flaky | A test is marked flaky |
| On Success | All tests pass |
| Suite Complete | All scheduled tests finish |
### Notification Channels
* **Email**: Send to any email address
* **Slack**: Post via incoming webhook
* **Discord**: Post via webhook
* **Microsoft Teams**: Post via connector webhook
## Next Steps
Auto-update tests when code changes
# FAQ
Source: https://docs.polarity.cc/faq
Common questions and troubleshooting.
## Getting Started
1. Install the GitHub App from the dashboard
2. Select which repositories to monitor
3. Enable automatic PR reviews in Settings
4. Paragon will automatically review new pull requests
For CLI access, install globally with `npm i -g @polarityinc/paragon` and authenticate with `paragon auth login`.
Your API key is located in the dashboard Settings page at the bottom. Click the copy button to copy it to your clipboard.
Use your API key to:
* Authenticate with the Paragon CLI (`paragon auth login`)
* Integrate with CI/CD pipelines
* Access the Paragon API directly
Keep your API key secure and never commit it to version control.
Paragon can only access repositories where:
* The GitHub App is installed
* You've explicitly enabled them in Settings → Automatic PR Reviews
You control exactly which repositories Paragon monitors. Add or remove repositories anytime from the dashboard.
## PR Reviews
Check the following:
1. **Repository not enabled** - Ensure the repo is added in Settings → Automatic PR Reviews
2. **Draft PR** - Draft PRs are only reviewed if "Draft PRs" is enabled in Review Options
3. **GitHub App permissions** - The app needs read access to pull requests and code
4. **Credit balance** - Check your remaining credits in the dashboard
If issues persist, try disconnecting and reconnecting your GitHub account in Settings.
To trigger a new review on an existing PR:
1. Push a new commit to the branch
2. Or close and reopen the PR
3. Or use the Paragon CLI: `paragon run -q "Review this PR"`
Each re-run consumes credits based on the PR size.
Yes, you can customize reviews in several ways:
* **Severity Filters** - Choose which severity levels to report (Critical, High, Medium, Low)
* **Custom Rules** - Add your own coding standards and guidelines
* **Review Options** - Enable/disable features like PR summaries, system diagrams, and commit suggestions
All customization options are available in the dashboard Settings page.
If "Out of Diff" is enabled, Paragon analyzes surrounding code context to find issues that may be affected by your changes but aren't directly in the diff.
To disable this, turn off "Out of Diff" in Settings → Review Options.
## Paragon CLI
Install globally via npm:
```bash theme={null}
npm i -g @polarityinc/paragon
```
Then authenticate:
```bash theme={null}
paragon auth login
```
Verify installation:
```bash theme={null}
paragon --version
```
* **`paragon run`** - Non-interactive, single prompt execution. Great for scripts and piping.
* **`paragon`** (no args) - Interactive terminal session with conversation history, slash commands, and model switching.
Use `paragon run` for automation and `paragon` for exploratory coding sessions.
Use stdin with `paragon run`:
```bash theme={null}
# Review a diff
git diff | paragon run -q "Review these changes"
# Analyze a file
cat src/auth.ts | paragon run "Explain this code"
# Review staged changes
git diff --staged | paragon run -q "Check for issues"
```
The `-q` flag hides the spinner for cleaner output.
## Billing & Credits
Credits are consumed when Paragon analyzes code:
* **Automatic PR reviews** - Credits based on PR size and complexity
* **CLI usage** - Credits based on tokens processed
* **Context queries** - Credits for semantic search and analysis
View your credit balance and usage statistics on the dashboard home page.
When credits are exhausted:
* Automatic PR reviews pause until credits are replenished
* CLI commands return an error with instructions to add credits
* Free plan credits reset monthly
* Paid plans can purchase additional credits anytime
Upgrade your plan or purchase credit top-ups from the Billing page.
## Troubleshooting
Try the following:
1. **Enable more severity levels** - Lower severities may be filtered out
2. **Check custom rules** - Conflicting rules may suppress findings
3. **Enable Out of Diff** - Issues may be outside the changed lines
4. **Increase context** - For CLI, provide more surrounding code
If Paragon consistently misses a type of issue, add a custom rule describing what to look for.
If you're having trouble with the GitHub connection:
1. Go to Settings → GitHub Connection
2. Click "Reconnect" to re-authorize
3. Ensure you grant access to the required repositories
4. Check that the GitHub App has the necessary permissions
You can also reinstall the GitHub App from [github.com/apps/paragon-review](https://github.com/apps/paragon-review).
If `paragon auth login` fails:
1. Ensure you have a valid API key from the dashboard
2. Check your internet connection
3. Try logging out first: `paragon auth logout`
4. Re-authenticate: `paragon auth login`
Run `paragon auth status` to verify your authentication state.
## Contact Support
Still have questions? Reach out to us:
* **Email**: [support@paragon.dev](mailto:support@paragon.dev)
* **GitHub Issues**: Report bugs or request features
# Overview
Source: https://docs.polarity.cc/index
AI-powered QA platform for bulletproof code.
Paragon is an AI-powered QA platform built with breakthrough research to help teams ship bulletproof code at unprecedented speed.
Paragon analyzes your GitHub repositories and creates intelligent pull requests with improvements for code quality, performance, and security.
## Core Features
[**/reviews** ->](/dashboard/issues)
Get automatic AI-powered code reviews on your pull requests. Tag @paragon-review to trigger reviews on-demand.
[**/testing** ->](/dashboard/testing/overview)
End-to-end testing infrastructure that catches bugs before they reach production.
[**/monitoring** ->](/dashboard/monitoring/overview)
Real-time monitoring and alerting for your applications with AI-powered insights.
[**/cli** ->](/paragon/overview)
AI-powered terminal assistant for writing, reviewing, and managing code from your command line.
## Get Started
Monitor repositories, view analytics, and configure settings
Install the GitHub App to connect your repositories
## Platform
Create and run automated tests across your codebase
Set up real-time monitoring and alerts
AI-powered terminal assistant for development
Connect with your existing tools and workflows
Spawn AI agents to autonomously explore and test a live web app
## AI Tools Integration
MCP server integration for Claude Code
MCP server integration for Cursor IDE
# Paragon MCP
Source: https://docs.polarity.cc/paragon-mcp
Connect Paragon to your AI coding tools via MCP
The Paragon MCP server gives your AI coding tools access to code review, testing, and analysis capabilities. Connect it to Claude Code, Cursor, or Windsurf to use Paragon directly from your development environment.
## Prerequisites
* [Paragon CLI installed](/paragon/overview)
* An API key from [app.paragon.run](https://app.paragon.run)
## Get your API key
1. Go to [app.paragon.run](https://app.paragon.run)
2. Sign in or create an account
3. Navigate to **Settings** → **API Keys**
4. Copy your API key
Some tools like `generate_tests`, `run_paragon`, `list_test_suites`, and `save_to_suite` require an API key. Other tools work without one.
## Connect to your tool
```bash theme={null}
claude mcp add-json paragon '{"command":"paragon","args":["mcp-server"],"env":{"POLARITY_API_KEY":"your-api-key-here"}}'
```
Replace `your-api-key-here` with your API key. Verify with:
```bash theme={null}
claude mcp list
```
[Full Claude Code setup guide →](/claude-code)
Open **Settings** → **MCP** → **+ Add new MCP server**, or add to `.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"paragon": {
"command": "paragon",
"args": ["mcp-server"],
"env": {
"POLARITY_API_KEY": "your-api-key-here"
}
}
}
}
```
Replace `your-api-key-here` with your API key. A green status indicator confirms the connection.
[Full Cursor setup guide →](/cursor)
Open **Cascade** → **Plugins (MCP)** → **Add custom server**, or add to `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"paragon": {
"command": "paragon",
"args": ["mcp-server"],
"env": {
"POLARITY_API_KEY": "your-api-key-here"
}
}
}
}
```
Replace `your-api-key-here` with your API key. Restart Windsurf and check for a green status indicator.
## Available tools
Once connected, Paragon exposes 12 tools to your AI coding assistant:
### Code review
| Tool | Description |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run_paragon` | Run a Paragon AI prompt — reads/writes files, runs shell commands, and performs complex coding tasks. Requires API key. |
| `list_reviewed_prs` | List pull requests with Paragon review comments in the current repository. Supports filtering by state (`open`, `closed`, `all`). |
| `get_review_comments` | Get parsed review findings from a PR, including severity, descriptions, file locations, and suggested fixes. Auto-detects PR from current branch if omitted. |
| `resolve_review_comment` | Reply to a review comment and optionally resolve the thread. |
### Testing
| Tool | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detect_test_framework` | Scan the repository and detect test frameworks in use. Returns framework details, run commands, file patterns, and confidence level. |
| `find_tests` | Discover existing test files using framework-aware file patterns. Returns file paths and count. |
| `run_tests` | Execute unit/integration tests using the detected or specified framework. Returns pass/fail status and full output. |
| `run_e2e_tests` | Run Playwright E2E tests locally. Installs browsers if needed, optionally starts a dev server, and captures results. |
| `generate_tests` | Generate unit, integration, or E2E tests using Paragon AI. Detects patterns, writes tests, verifies compilation, runs them, and fixes failures. Requires API key. |
### Test suite management
| Tool | Description |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `list_test_suites` | List your test repositories and suites from the Paragon cloud dashboard. Requires API key. |
| `save_to_suite` | Save locally generated test files to a Paragon cloud test suite. Requires API key. |
### Utility
| Tool | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `check_setup` | Check if the MCP server is properly configured. Reports the status of the API key, Paragon binary, and GitHub CLI. |
## Example prompts
After setup, your AI tool can automatically use Paragon when relevant. You can also request tools directly:
```
Review the comments on my current PR and fix the issues
Generate unit tests for src/auth.ts
Run the test suite and show me what's failing
Find all Playwright tests and run them in headed mode
```
# Autotest
Source: https://docs.polarity.cc/paragon/auto-test
Spawn AI agents to autonomously explore and test a live web application.
Spawn parallel AI agents that navigate a live web application using a real browser, find bugs, take screenshots, and optionally create GitHub issues or PRs with their findings.
```bash theme={null}
paragon autotest [description] [flags]
```
Unlike `paragon test` which runs pre-written Playwright tests, `autotest` uses AI agents that explore your app autonomously — no test files needed. Each agent gets its own isolated browser instance.
## How It Works
1. **Planning** — A planning agent analyzes the target app and distributes testing work across agents.
2. **Exploration** — Each agent navigates the app in a real browser, performing actions like clicking, typing, scrolling, and navigating between pages.
3. **Reporting** — Findings are compiled into a report with screenshots, reproduction steps, and severity ratings. Playwright test code is auto-generated from the agent's actions.
4. **GitHub integration** (optional) — Findings are filed as GitHub issues or bundled into a PR.
## Flags
| Flag | Type | Default | Description |
| --------------- | -------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--url` | `string` | **(required)** | Target URL to test. |
| `--prompt` | `string` | — | What to test (e.g. `"test the checkout flow"`). |
| `--agents` | `int` | `1` | Number of parallel agents (1–8). Each agent gets its own browser. |
| `--model` | `string` | `paragon-max` | Model to use for the agents. |
| `--timeout` | `int` | `15` | Per-agent timeout in minutes. |
| `--auth` | `string` | — | Path to a cookies JSON file (browser-use export format) for pre-authenticated sessions. |
| `--login` | `string` | — | Login instructions for the agent in plain English (e.g. `"click Login, type user@test.com into email, type pass123 into password, click Submit"`). |
| `--session` | `string` | — | Team auth session name or ID stored in Supabase. |
| `--repo` | `string` | — | GitHub repo for issue/PR creation (`owner/repo`). |
| `--pr` | `bool` | `false` | Create a PR with findings instead of an issue. Defaults to `true` when `--repo` is set. |
| `--skip-github` | `bool` | `false` | Skip GitHub issue/PR creation even if `--repo` is set. |
| `--json` | `bool` | `false` | Output results as structured JSON. |
| `-q, --quiet` | `bool` | `false` | Minimal output. |
## Examples
```bash theme={null}
# Basic: test a local app
paragon autotest --url http://localhost:3000 --prompt "make sure the page loads"
# Run against production with multiple agents
paragon autotest --url https://yourapp.com --prompt "test the checkout flow" --agents 4
# Test with login instructions
paragon autotest --url https://yourapp.com --login "click Login, type user@test.com into email, type pass123 into password, click Submit" --prompt "test the dashboard"
# Use a cookies file for auth
paragon autotest --url https://yourapp.com --auth ./cookies.json --prompt "test account settings"
# Use a shared team auth session
paragon autotest --url https://yourapp.com --session "staging-admin" --prompt "test admin panel"
# File findings as a GitHub PR
paragon autotest --url https://yourapp.com --prompt "test user registration" --repo acme/webapp --pr
# Skip GitHub, just see findings locally
paragon autotest --url http://localhost:3000 --prompt "test login" --skip-github
# JSON output for CI pipelines
paragon autotest --url https://yourapp.com --prompt "smoke test" --json --quiet
```
## Authentication
Autotest supports three ways to authenticate agents with your app:
| Method | Flag | When to use |
| ---------------------- | ----------- | ------------------------------------------------------------------ |
| **Login instructions** | `--login` | Simple login forms. Describe the steps in plain English. |
| **Cookies file** | `--auth` | Export cookies from browser-use and pass the JSON file. |
| **Team session** | `--session` | Shared, encrypted auth sessions stored in Supabase for team reuse. |
## Managing Team Auth Sessions
Use `paragon autotest auth` to manage shared authentication sessions:
```bash theme={null}
# List all team auth sessions
paragon autotest auth list
# Capture a new session (opens a browser — log in manually, then close)
paragon autotest auth capture https://yourapp.com --name "staging-admin"
# Use the captured session
paragon autotest --url https://yourapp.com --session "staging-admin" --prompt "test dashboard"
# Delete a session
paragon autotest auth delete "staging-admin"
```
## Output
Each finding includes:
* **Title and description** of the bug
* **Severity** rating (`critical`, `high`, `medium`, `low`)
* **Screenshots** captured during the session
* **Reproduction steps** from the agent's browser actions
* **URL** where the issue was found
* **Auto-generated Playwright code** to reproduce the bug
When `--repo` is set, findings are automatically filed as GitHub issues or bundled into a PR with the generated Playwright tests.
# Slash Commands
Source: https://docs.polarity.cc/paragon/commands
Complete reference for all Paragon CLI slash commands.
Type these commands directly in the input field. Start typing `/` to see autocomplete suggestions.
## `/model`
**Switch to a different model.** Opens a model selection dialog where you can choose between available LLM models.
## `/session`
**Switch to a different session.** Opens a session picker showing all your previous conversation sessions. Each session maintains its own context and history.
## `/new`
**Start a new session.** Creates a fresh conversation session with no prior context.
## `/compact`
**Summarize current session.** Creates a summary of the current conversation and starts a new session with that summary as context. Use when:
* Approaching context window limits (auto-prompted at 95%)
* Want to condense a long conversation
* Starting a related but distinct task
## `/approvals`
**Toggle auto-approve (yolo) mode.** Toggles automatic approval of all tool executions:
| Mode | Behavior |
| ------------------ | -------------------------------------------------------------------- |
| **OFF** (default) | Paragon asks permission before running commands, editing files, etc. |
| **ON** (yolo mode) | All tool calls are automatically approved |
Use with caution - yolo mode will execute commands without confirmation.
## `/feature`
**Toggle feature mode.** Enables/disables Feature Mode which changes how the agent approaches tasks:
| Mode | Behavior |
| ------- | -------------------------------------------------------------------- |
| **OFF** | Standard assistant behavior |
| **ON** | Agent focuses on implementing complete features with better planning |
## `/init`
**Create/Update PARAGON.md memory file.** Generates or updates a `PARAGON.md` file in your project root containing:
* Project overview and architecture
* Key conventions and patterns
* Important files and their purposes
* Development guidelines
This file is automatically read by Paragon to understand your project context.
## `/infra`
**Generate INFRA.md and infrastructure diagram.** Analyzes your project and creates:
* `INFRA.md` - Infrastructure documentation
* Mermaid diagram showing system architecture
## `/status`
**View account status and credits.** Opens a dialog showing:
* Current user and team information
* Remaining token credits
* Usage statistics
* Plan/subscription details
Requires Paragon authentication (`paragon auth login`).
## `/help`
**Toggle help display.** Shows/hides the keyboard shortcut help bar at the bottom of the screen.
## `/quit`
**Quit Paragon.** Exits the application. Same as `ctrl+c` or typing `exit`/`quit` in the input.
# Configuration
Source: https://docs.polarity.cc/paragon/configuration
Configure Paragon with project files and authentication.
## paragon.json
Create a `paragon.json` file in your project root to configure Paragon behavior:
```json theme={null}
{
"automations": [
{
"name": "Build & Test",
"prompts": [
"Run the build",
"Run all tests",
"Report any failures"
]
}
]
}
```
## PARAGON.md
Use `/init` to generate a `PARAGON.md` file that provides project context to Paragon. This file should contain:
* Project structure overview
* Key technologies and frameworks
* Development conventions
* Important architectural decisions
## Authentication
### Login
```bash theme={null}
paragon auth login
```
Opens a browser-based authentication flow to connect your Paragon account.
### Status
```bash theme={null}
paragon auth status
```
Displays current authentication state and account information.
### Logout
```bash theme={null}
paragon auth logout
```
Removes stored credentials.
## FAQ
Use the `/model` command to open the model picker and select a different model. Your conversation context is preserved.
Sessions are separate conversations with independent context. `/compact` summarizes your current session and starts fresh with that summary as context.
MCP (Model Context Protocol) servers extend Paragon's capabilities by connecting to external tools and services. Configure them via `/mcp` to give Paragon access to filesystems, databases, APIs, and more.
Yolo mode (`/approvals`) auto-approves all tool executions. Use it only when you trust the operations being performed and want faster iteration. You can toggle it off at any time.
Monitors are scheduled tasks that run Paragon prompts at regular intervals. They require Polarity authentication and run in the background based on your configured cadence.
Paragon requires an internet connection to communicate with AI models. Some MCP servers may work offline if they only access local resources.
## Getting Help
* Use `/help` to view keyboard shortcuts
* Run `paragon --help` for CLI options
* Contact [support@polarity.com](mailto:support@polarity.com) for assistance
# E2E Testing
Source: https://docs.polarity.cc/paragon/e2e-testing
Generate and run end-to-end tests using natural language.
Paragon generates and runs Playwright tests from plain English. Describe what you want to test, and Paragon handles the rest.
## Quick Start
Just tell Paragon what to test:
```
Test the checkout flow with an expired credit card
```
Paragon writes the Playwright test, runs it, and opens an HTML report with video recordings and tracing so you can see exactly what happened.
## How It Works
1. **Describe the test** in natural language
2. **Paragon generates** Playwright tests and saves a scenario to `paragon.json`
3. **View results** with video recordings, tracing, and screenshots
Tests run on your actual machine with your real environment variables, secrets, and local services.
## Running Saved Tests
Once a scenario is saved, run it anytime:
| Method | How |
| -------- | --------------------------------- |
| **CLI** | `paragon tests run ` |
| **Chat** | "run my e2e tests" |
| **TUI** | `ctrl+p` → Automation Scenarios |
## `paragon test`
Run exported Playwright E2E tests locally from the terminal. This command wraps `npx playwright test` with your `paragon-tests/` configuration and handles authentication with Polarity for AI-powered test steps.
```bash theme={null}
paragon test [file-pattern] [flags]
```
### Prerequisites
Before running `paragon test`, make sure:
1. **You're authenticated** — run `paragon auth login` if you haven't already. AI-powered test steps require a valid Polarity session.
2. **You have a `paragon-tests/` directory** in your project root containing a `playwright.config.ts`. Export your tests from the [Paragon Dashboard](https://home.polarity.cc/app/testing/e2e) to generate this directory.
3. **Playwright is available** — the command runs via `npx`, so Playwright will be resolved from your project's `node_modules` or fetched automatically.
If the `paragon-tests/` directory or `playwright.config.ts` is missing, the command will exit with an error and point you to the dashboard to export your tests.
### Basic Usage
```bash theme={null}
# Run all tests in paragon-tests/
paragon test
# Run a specific test file
paragon test login.spec.ts
# Run multiple files or use glob patterns
paragon test auth.spec.ts checkout.spec.ts
paragon test **/*.spec.ts
```
The optional `[file-pattern]` argument accepts one or more file paths or glob patterns. When omitted, all tests in the `paragon-tests/` directory are run.
### Flags
| Flag | Type | Default | Description |
| ----------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--url` | `string` | — | Base URL for tests. Sets the `PARAGON_TEST_URL` environment variable, overriding the URL configured in `playwright.config.ts`. Also overridable via the `PARAGON_TEST_URL` env var directly. |
| `--headed` | `bool` | `false` | Run tests with a visible browser window instead of headless mode. Useful for watching tests execute in real time. |
| `--grep` | `string` | — | Filter tests by name or pattern. Only tests whose name matches the pattern will run. Passed directly to Playwright's `--grep` flag. |
| `--workers` | `int` | `0` (auto) | Number of parallel worker processes. When set to `0`, Playwright chooses automatically. Set to `1` to run tests sequentially. |
| `--retries` | `int` | `0` | Number of times to retry failed tests. Useful for flaky tests or unstable environments. |
| `--timeout` | `int` | `0` | Test timeout in milliseconds. Overrides the timeout set in your Playwright config. When `0`, the config default is used (typically 300,000ms / 5 minutes). |
| `--project` | `string` | — | Run tests for a specific browser project defined in your Playwright config (e.g. `chromium`, `chrome`, `firefox`). |
| `--debug` | `bool` | `false` | Launch Playwright in debug mode. Opens the Playwright Inspector, allowing you to step through tests, inspect selectors, and view logs interactively. |
| `--ui` | `bool` | `false` | Open Playwright's interactive UI mode. Provides a visual interface for browsing, running, and debugging tests with a built-in trace viewer. |
### Examples
```bash theme={null}
# Run all tests against your local dev server
paragon test --url http://localhost:3000
# Watch tests run in a visible browser
paragon test --headed
# Filter to only run tests with "login" in the name
paragon test --grep "login"
# Run a single file in Chrome only
paragon test checkout.spec.ts --project chromium
# Retry flaky tests up to 3 times with a longer timeout
paragon test --retries 3 --timeout 120000
# Step through a test interactively with the Playwright Inspector
paragon test --debug --headed
# Open the full Playwright UI for exploring all tests
paragon test --ui
# Combine flags for a targeted local run
paragon test --url http://localhost:3000 --headed --grep "checkout" --workers 4
```
### Running Against Production
Use the `--url` flag to point tests at a deployed environment:
```bash theme={null}
# Run against a staging environment
paragon test --url https://staging.yourapp.com
# Run against production
paragon test --url https://yourapp.com --project chromium --retries 2
```
You can also set the `PARAGON_TEST_URL` environment variable instead of passing `--url` each time:
```bash theme={null}
export PARAGON_TEST_URL=https://staging.yourapp.com
paragon test
```
When `--url` is provided, it takes precedence over the env var.
### Default Playwright Configuration
Exported tests come with a pre-configured `playwright.config.ts` that includes sensible defaults:
| Setting | Default |
| ---------------- | --------------------- |
| Timeout | 300,000ms (5 minutes) |
| Expect timeout | 30,000ms |
| Workers | 1 (sequential) |
| Retries | 0 |
| Video recording | Enabled |
| Trace collection | Enabled |
| Screenshots | Enabled |
| Viewport | 1280 x 720 |
| Browsers | Chromium, Chrome |
Test results including videos, traces, and screenshots are written to a `test-results/` directory.
Use `--ui` mode for the best local debugging experience — it gives you a visual test explorer with a built-in trace viewer, video playback, and DOM snapshots.
# Overview
Source: https://docs.polarity.cc/paragon/overview
AI-powered terminal assistant for code development, featuring model switching, MCP integrations, and workflow automation.
Paragon is an AI-powered terminal assistant that helps you write, review, and manage code directly from your command line. It features model switching, MCP server integrations, custom agents, automated workflows, and intelligent code assistance.
## Installation
Install Paragon globally via npm:
```bash theme={null}
npm i -g @polarityinc/paragon
```
After installation, authenticate with your Paragon account:
```bash theme={null}
paragon auth login
```
You can find the API key in the dashboard under the settings tab at the bottom of the page.
```bash theme={null}
paragon
```
## Models
Paragon supports multiple AI models with different capabilities:
| Model | Description |
| -------------- | ----------------------------------------- |
| `paragon-fast` | Quick responses, lower cost |
| `paragon-mid` | Balanced performance and cost |
| `paragon-high` | Higher quality responses |
| `paragon-max` | Maximum capability with extended thinking |
Models with thinking/reasoning capabilities will show a budget indicator.
## Keyboard Shortcuts
| Shortcut | Action |
| -------- | -------------------- |
| `ctrl+p` | Open command palette |
| `ctrl+n` | New session |
| `ctrl+s` | Switch session |
| `ctrl+t` | Reopen tasks dialog |
| `ctrl+f` | File picker |
| `ctrl+o` | External editor |
| `ctrl+g` | Toggle help |
| `ctrl+c` | Quit |
| `ctrl+z` | Suspend to shell |
## Additional Features
### File Attachments
Type `@` in the input to get file path completions. Attach images or files to your message for the AI to analyze.
### Preference Memory
| Prefix | Scope | Example |
| ------ | ---------------------------- | --------------------------------------- |
| `#` | Global (all projects) | `# Always use TypeScript for new files` |
| `##` | Local (this repository only) | `## Use Vitest for testing` |
# Tools & Automation
Source: https://docs.polarity.cc/paragon/tools
MCP servers, custom agents, automations, and scheduled monitors.
## `/mcp` - MCP Servers
**Manage MCP (Model Context Protocol) servers.** Opens the MCP Manager dialog where you can configure external tool integrations.
### Adding MCP Servers
1. Select `/mcp` to open the manager
2. Choose "Add Server" or press `a`
3. Select server type:
* **stdio** - Local process (most common)
* **http** - HTTP endpoint
* **sse** - Server-Sent Events
### For stdio servers
| Field | Description |
| ----------- | ------------------------------------------- |
| **Name** | Unique identifier for the server |
| **Command** | The executable (e.g., `npx`, `uvx`, `node`) |
| **Args** | Command arguments as JSON array |
| **Env** | Environment variables as JSON object |
### Common MCP Server Examples
**Filesystem access:**
```
Command: npx
Args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
```
**GitHub:**
```
Command: npx
Args: ["-y", "@modelcontextprotocol/server-github"]
Env: {"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"}
```
**PostgreSQL:**
```
Command: npx
Args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]
```
### Managing Servers
* **Enable/Disable**: Toggle servers on/off without removing them
* **Authenticate**: Some servers require OAuth or API key authentication
* **Delete**: Remove servers you no longer need
## `/agents` - Custom Agents
**Manage custom subagents.** Opens the Agents (Droids) manager where you can create specialized AI agents with:
* **Custom system prompts** - Define the agent's personality and expertise
* **Specific models** - Choose which model powers the agent
* **Tool restrictions** - Limit which tools the agent can use
Use cases:
* Code reviewer agent with strict guidelines
* Documentation writer with specific style
* Test generator focused on edge cases
## `/automations` - Workflow Automation
**Run saved E2E/regression flows.** Opens the Automation Scenarios dialog. Automations are predefined sequences of prompts that run automatically.
Configure in `paragon.json`:
```json theme={null}
{
"automations": [
{
"name": "Full Test Suite",
"prompts": [
"Run all unit tests",
"Run integration tests",
"Generate coverage report"
]
}
]
}
```
## `/monitors` - Scheduled Tasks
**Manage scheduled monitors.** Opens the Monitors dialog for creating automated scheduled tasks.
### Creating a Monitor
1. Press `a` to add new monitor
2. Enter a **prompt** - what you want the monitor to check/do
3. Select **cadence**:
* **Hourly** - Runs every hour
* **Daily** - Runs once per day
* **Weekly** - Runs once per week
4. Press `Enter` to save
### Managing Monitors
| Key | Action |
| ------- | ----------------------- |
| `a` | Add new monitor |
| `Enter` | Edit selected monitor |
| `t` | Toggle enabled/disabled |
| `d` | Delete monitor |
| `↑/↓` | Navigate list |
| `Esc` | Close dialog |
### Use Cases
* Daily code quality checks
* Weekly dependency audits
* Hourly log monitoring
* Scheduled report generation
Requires Paragon authentication (`paragon auth login`).