Prompt guide

Learn how to write effective prompts for each Test Companion capability, with examples and tips for better results.

The clearer your prompt, the better the output. This page covers prompt structure, context strategies, and examples for every capability.

Prompt structure

A strong prompt has three parts:

1. The task: What you want Test Companion to do. Start with an action verb.
2. The scope: What area, feature, or file the task applies to.
3. The constraints: Any specific requirements, frameworks, formats, or boundaries.

Weak prompt:

Test my app.

Strong prompt:

Test the checkout flow on localhost:3000/checkout. Verify that adding, removing, and
updating cart quantities works correctly. Check edge cases like zero quantity and
negative values.

The weak prompt forces Test Companion to guess what “app” means, which pages to visit, and what to look for. The strong prompt gives a clear task, a defined scope, and specific constraints.

Context strategies

Adding context alongside your prompt improves accuracy. You can combine multiple context types in a single message.

Attach files

Click the + icon to attach documents like PRDs, specs, images, or screenshots. Attached files give Test Companion the full source material to work from.

Best for: Generating test cases from requirements. Providing visual references for UI testing.

Use @ references

Type @ in the chat to reference items from your workspace:

• @Files: Reference specific source files or test files.
• @Folders: Reference an entire directory for broader context.
• @Git Commits: Reference recent commits so Test Companion understands what changed.
• @Terminal: Reference terminal output, including error messages from failed builds.

Best for: Validating code changes. Fixing failed tests. Adding project-specific context.

Paste text directly

Type or paste requirements, error messages, API responses, or any text directly into the chat.

Best for: Quick tasks where you already have the information on your clipboard. Sharing error logs from external CI/CD systems.

Examples by capability

These examples show how to structure prompts for each Test Companion capability. Use them as templates and adapt the scope, constraints, and context to match your specific testing needs.

Generate test cases

From a requirement document:

Generate test cases for the attached PRD. Focus on the payment processing flow.
Include positive, negative, and edge case scenarios.

From a live website:

Explore example.com/products and generate test cases. Focus on search, filtering,
sorting, and pagination. Check for empty state handling.

Targeted scope:

Generate test cases for the email validation logic described in @src/validators/email.ts.
Cover valid formats, invalid formats, Unicode characters, and maximum length.

Validate code changes

Focused validation:

Test my latest changes on localhost:3000. I modified the user profile form to add
phone number validation. Check that valid and invalid phone numbers are handled correctly.

Git-aware validation:

Validate the changes in my last 2 git commits on localhost:8080. Focus on the areas I modified.

Edge case testing:

Test the price range filter on localhost:3000/products. Check what happens when min
equals max, when both are zero, and when max is less than min.

Automate tests

From a prompt:

Write a Playwright test that logs in to localhost:3000/login with username "admin"
and password "admin123", navigates to the settings page, and verifies the account
email is displayed.

From existing tests:

Convert the selected test cases to Cypress tests. Use the Page Object Model pattern.
Store page objects in tests/pages/.

API testing:

Generate API tests for POST /api/v1/users at localhost:3000. Test successful creation
with valid data, validation errors for missing fields, and duplicate email handling.
Use the Jest framework.

Fix failed tests

With error details:

Fix this failure:
TimeoutError: locator.click: Timeout 30000ms exceeded.
Waiting for selector '[data-testid="submit-btn"]'
The test file is @tests/e2e/checkout.spec.ts and the component is @src/components/Checkout.tsx.

With build context:

My CI build failed with 3 test errors. All are related to the updated API response format.
The new response wraps data in a `results` array instead of returning it at the top level.
Update the test assertions.

Fix accessibility violations

Full scan:

Scan localhost:3000 for all accessibility violations. Fix everything that is Critical or Serious.

Targeted scan:

Check the signup form at localhost:3000/register for accessibility issues.
Focus on form labels, error messages, and keyboard navigation.

Post-fix verification:

Re-scan localhost:3000/checkout. I applied your previous fixes and want to confirm
all issues are resolved.

Common prompt patterns

• Do X on Y: Direct instruction with a target. Example: Generate test cases for the login page on example.com.
• Fix this [error]: Troubleshooting with context. Example: Fix this timeout error in @tests/checkout.spec.ts.
• Convert these to [format]: Transformation. Example: Convert the selected manual tests to Playwright scripts.
• Scan [target] for [issues]: Analysis with scope. Example: Scan localhost:3000 for color contrast violations.
• Verify that [condition]: Validation with assertion. Example: Verify that the cart total updates when I change item quantity on localhost:3000/cart.

Next steps

• Test Companion overview: Review all available capabilities.
• AI settings: Adjust permissions to match your workflow.