FAQ & Troubleshooting

This means the OAuth session has expired or was never started properly. Don't visit /login directly — the login flow is triggered automatically by your MCP client.

Fix: Restart the MCP connection from your IDE (disconnect and reconnect). A new login session will be initiated.

OAuth tokens last 8 hours and auto-refresh. If you start getting authentication errors after a long session, simply disconnect and reconnect your MCP client — you'll be prompted to log in again.

Yes. Everyone points their IDE config to the same MCP URL. Each person authenticates with their own ContextQA credentials. Their sessions and workspaces are isolated.

Test executions typically take 30–120 seconds depending on the number of steps. Ask your AI assistant:

What's the execution status of test case [ID]?

This will poll the status and tell you if it's still running, completed, or failed. If it's truly stuck, the execution will eventually time out.

Check your workspace ID. The MCP server uses the workspace selected for your connection. Ask for your current workspace and accessible workspaces, then switch using a workspace version id. The selection persists in your OAuth session. To check the organization as well, ask who you are signed in as.

Try listing all test cases without filters first:

Show my current workspace, list the workspaces I can access, and list my test cases

Before running a mobile test, you need to check available devices and apps:

Show me available android devices and apps

Common issues:

• The device name must match exactly (case-sensitive)
• The app must be uploaded and available in your workspace
• The test case must be created with test_type: MOBILE

Yes. When asking to run a test, specify that you want it to run in the portal:

Run test case [ID] in the portal so I can watch it live.

This sets run_in_portal: true and opens the execution in the ContextQA web dashboard.

No. The AI and ContextQA use visual/semantic matching to find elements. Describing elements by their visible text or role is usually enough:

• "Click the Sign In button" — works via text matching
• "Enter text in the email field" — works via label/placeholder matching
• "Verify the Dashboard heading appears" — works via content matching

If you do know the selector, including it can improve precision, but it's not required.

Yes! You can ask for multi-step operations. The AI will call the right tools in sequence:

Create a test case for the login flow on https://myapp.com,
run it, and if it fails, investigate the failure and show me
the network logs.

The AI handles the orchestration — creating the test, executing it, polling for results, and if it fails, calling the investigation and network log tools.

No. Just describe what you want in natural language. The AI selects the right tool, fills in the parameters, and returns the results. You never need to call a tool by name.

The Prompt Library has copy-paste templates for every use case.

A test suite groups test cases. A test plan defines execution: it attaches suites to browsers/devices and includes run settings, tracking, history, and reporting. Run a suite through a test plan.

Think of it as: Test Cases → Test Suites → Test Plans (from specific to broad).

Knowledge bases are custom instruction sets that guide how tests are generated and executed. They're useful when you have domain-specific rules that should be applied across tests.

Examples:

• "Always check for ARIA labels on interactive elements"
• "Wait 3 seconds after page load for the SPA to hydrate"
• "Skip the cookie consent popup by clicking Accept first"

Create one and reference it when running tests for consistent behavior.

Yes. For Playwright, the tool returns a project file manifest for your assistant to save on your computer. Other framework export paths use the server filesystem. See the export reference:

Export test cases 10, 15, and 22 as a Playwright TypeScript
project to ./e2e-tests

This generates a complete project with package.json, config, and test files that you can run in your CI/CD pipeline.

Any MCP-compatible client. Currently supported:

• Claude Code (CLI, desktop, VS Code extension)
• Cursor
• VS Code (with MCP extension)
• n8n (workflow automation)
• Any client that supports the Model Context Protocol

The MCP provides tools for the AI to use — it doesn't control the AI itself. Limitations:

• It can't directly modify your application code (only suggest fixes)
• It can't deploy your application (you do that)
• It can't access systems outside ContextQA (no Slack, email, etc.)
• It can't bypass ContextQA's own workspace permissions
• Complex conditional logic in tests might need manual step editing