QA Guardian Command Line Interface

Trigger and monitor test suite executions from the command line.

Installation

npm install -g qaguardian

Or use directly with npx:

npx qaguardian --tags smoke

Quick Start

# Set your API key
export QAGUARDIAN_API_KEY=your-api-key-here

# Run suites with specific tags
npx qaguardian --tags auth,login

# Exclude certain tags
npx qaguardian --tags regression --exclude-tags slow,flaky

# Run all suites
npx qaguardian --all

# Fire and forget (no polling)
npx qaguardian --tags smoke --no-wait

Options

• --tags <tags> - Comma-separated tags to match (e.g., "auth,ci,smoke")
• --exclude-tags <tags> - Comma-separated tags to exclude (e.g., "slow,flaky")
• --all - Run all suites (combine with --exclude-tags to filter)
• --match-mode <mode> - Tag matching mode: "any" (OR logic, default) or "all" (AND logic)
• --no-wait - Trigger and exit immediately without waiting for results
• --webhook-url <url> - Custom webhook URL for notifications on completion
• --notify <service> - Notify via service: slack, discord, google-chat, or teams
• --api-url <url> - Custom API Gateway URL (default: https://api.qaguardian.com)

Environment Variables

• QAGUARDIAN_API_KEY - (Required) Your QA Guardian API key
• QAGUARDIAN_API_URL - (Optional) API Gateway URL (defaults to https://api.qaguardian.com)

Examples

Tag-based execution with wait

export QAGUARDIAN_API_KEY=guardians-primary-qag-cbaa125e027b417a
npx qaguardian --tags auth,ci

Exclude certain tags

npx qaguardian --tags regression --exclude-tags slow,flaky

Run everything except auth suites

npx qaguardian --all --exclude-tags auth

Fire and forget

npx qaguardian --tags smoke --no-wait

AND logic (all tags required)

npx qaguardian --tags auth,login,ui --match-mode all

Notifications

Receive notifications when tests complete:

# Custom webhook URL
npx qaguardian --tags regression --webhook-url https://my-service.com/webhook

# Slack notification
npx qaguardian --tags smoke --notify slack

# Discord notification
npx qaguardian --tags auth --notify discord

# Google Chat notification
npx qaguardian --tags ci --notify google-chat

# Microsoft Teams notification
npx qaguardian --tags regression --notify teams

Local development

cd qaguardian
npm install
npm link
export QAGUARDIAN_API_KEY=your-api-key
npx qaguardian --tags smoke --api-url http://localhost:8080

Exit Codes

• 0 - All tests passed
• 1 - Any test failed or execution failed

API Key

Get your API key from the QA Guardian dashboard at: https://app.qaguardian.com/settings/api-keys

Polling Behavior

By default, the CLI polls the API every 30 seconds to check for completion. You can observe:

• Real-time test count updates
• Pass/fail counts as tests complete
• Automatic exit with appropriate code when all suites finish

Use --no-wait to skip polling and exit immediately after triggering.

Notifications

The CLI can send notifications when test suites complete. Choose one of:

Webhook Notifications

Send results to any HTTP endpoint:

qaguardian --tags regression --webhook-url https://my-service.com/webhook

The webhook receives a POST request with execution results.

Platform Notifications

Integrated notification support for popular chat and communication platforms:

• Slack: --notify slack (requires Slack integration configured in QA Guardian)
• Discord: --notify discord (requires Discord integration configured)
• Google Chat: --notify google-chat (requires Google Chat integration configured)
• Microsoft Teams: --notify teams (requires Teams integration configured)

Example:

qaguardian --tags smoke --notify slack

Notifications are sent when all tests complete, with summary of pass/fail counts.

Publishing

Requires maintainer access on npmjs.com/package/qaguardian.

Steps

1. Bump the version in package.json
2. Commit: git commit -m "vX.Y.Z"
3. Log in to npm (first time or if session expired):

   npm login

4. Publish:

   npm publish --access public

   npm will open a browser tab to complete authentication (email OTP).

Automated publishing (CI)

Generate a Classic Automation Token at https://www.npmjs.com/settings/~/tokens and store it as NPM_TOKEN in GitLab CI/CD variables. Then publish without interactive auth:

NPM_CONFIG_AUTH_TOKEN=$NPM_TOKEN npm publish --access public

License

MIT