Help Center

Welcome to the TrueAssert Help Center. Find answers to common questions, troubleshooting guides, and tips to get the most out of TrueAssert.

🚀 Getting Started

New to TrueAssert? Start here:

❓ Frequently Asked Questions

Account & Setup

Q: How do I create an account? A: Visit the registration page and fill in your details. A default organization and project are automatically created for you.

Q: Do I need to create an organization or project manually? A: No, a default organization and project are created automatically when you register. You can use these immediately or create additional ones later.

Q: How do I get an API key? A: After logging in, go to the Agents page. Click "Create API Key" to generate a new key. Copy and save it securely - you'll need it for the browser plugin.

Q: Can I have multiple API keys? A: Yes, you can create multiple API keys. Each key is linked to your account and organization.

Browser Plugin

Q: How do I install the browser plugin? A: Download the plugin ZIP file from the Agents page, then install it in Chrome using "Load unpacked" from the Extensions page. See the Installation Guide for detailed steps.

Q: The plugin won't connect. What should I do? A:

  1. Verify your API key is correct (no extra spaces)

  2. Check that you copied the full API key

  3. Try disconnecting and reconnecting

  4. Refresh the plugin popup

Q: Recording isn't starting. Why? A:

  • Ensure you're on a valid webpage (not chrome:// or extension pages)

  • Check that the content script is loaded (refresh the page)

  • Verify the plugin is authenticated

  • Try closing and reopening the plugin popup

Q: Steps aren't being captured during recording. A:

  • Some JavaScript frameworks may prevent event capture

  • Try clicking elements directly instead of using keyboard shortcuts

  • Check browser console for errors

  • Ensure the page has fully loaded before starting recording

Test Creation

Q: How do I create a test? A: You have three options:

  1. Browser Plugin Recording - Record your interactions (recommended for most users)

  2. AI Test Generation - Describe what you want to test in natural language

  3. Manual Creation - Build tests step-by-step using the web interface

See Your First Test for details.

Q: Which method should I use to create tests? A:

  • Recording: Best for most users - fastest and most intuitive

  • AI Generation: Good for complex flows or when you want to describe requirements

  • Manual: Use when you need precise control or want to edit existing tests

Q: How long does AI test generation take? A: Typically 30-60 seconds, depending on test complexity and page size. The test status will update from DRAFTING → REVIEW → READY.

Q: My AI-generated test has incorrect steps. What should I do? A: You can edit any test step manually. Go to the test detail page, click "Edit" on any step, and update the selector, value, or action type.

Test Execution

Q: How do I run a test? A: Go to the test detail page and click the "Run Test" button. The test will execute and you can monitor progress in real-time.

Q: Why is my test stuck in "IN_QUEUE" status? A: This means no agents are available. Check the Agents page to see agent status. Ensure at least one agent is connected and available.

Q: My test is stuck in "RUNNING" status. A:

  • The test may still be executing (check progress bar)

  • Agent may have disconnected (check agent status)

  • Command may have timed out (check execution logs)

Q: How long do tests take to run? A: Depends on test complexity:

  • Simple tests (5-10 steps): 10-20 seconds

  • Complex tests (20+ steps): 30-60 seconds

  • With login: Add 10-15 seconds for full login, or 2-3 seconds for session validation

Selectors & Elements

Q: What are XPath selectors? A: XPath is a query language for selecting elements in HTML. TrueAssert automatically generates XPath selectors that are more robust than CSS selectors. See Understanding XPath Selectors.

Q: My selector keeps breaking. How do I fix it? A:

  1. Update to use ID or data-testid selectors (most stable)

  2. Check if element still exists on page

  3. Add WAIT step if element loads slowly

  4. Review Selector Best Practices

Q: Can I use CSS selectors instead of XPath? A: Yes, you can choose CSS or XPath when creating or editing steps. However, XPath is recommended for better reliability with complex pages.

Q: How do I get a selector for an element? A: Use the browser plugin's "Selector" feature. Click "Selector" in the plugin, then click the element on the page. The XPath selector will be generated and displayed.

Session Management & Login

Q: How do I set up login for my tests? A: Go to Project Settings → Login, enter your login URL, username, and password, then save. A login test will be automatically generated. See Setting Up Login.

Q: What's the difference between "Login Required" and "Use Predefined Session"? A:

  • Login Required: Test will execute login flow if needed (session validation or full login)

  • Use Predefined Session: Test will load existing session data (faster, but requires session to exist)

Q: Why does my test always do a full login? A: This happens when:

  • No session exists yet (first run)

  • Session validation failed (session expired)

  • Session domain doesn't match test URL domain

Q: How do I clear a saved session? A: Go to Project Settings → Session, and clear the session data. A new session will be created on the next test run.

Q: My session validation always fails. A:

  • Check that validation steps in login test are correct

  • Verify confirmation element still exists

  • Clear session and create a new one

  • Update login test validation steps if page changed

Test Results & Debugging

Q: How do I view test results? A: Go to the test detail page. You'll see execution status, step-by-step results, screenshots, and error messages. See Viewing Results.

Q: My test failed. How do I debug it? A:

  1. Check the error message for the failed step

  2. View the screenshot at the failure point

  3. Review execution logs

  4. See Debugging Failed Tests for detailed guidance

Q: Why did my test fail with "Element not found"? A:

  • Element doesn't exist on page

  • Element hasn't loaded yet (add WAIT step)

  • Selector is incorrect (update selector)

  • Page structure changed (update selector)

Q: How do I see screenshots from test execution? A: On the test detail page, click on any step result. Screenshots are captured after each step (if enabled) and automatically on failures.

Organization & Projects

Q: What's the difference between organizations and projects? A:

  • Organizations: Top-level grouping (companies, teams)

  • Projects: Sub-grouping within organizations (applications, features)

  • Tests: Individual test cases within projects

Q: Can I have multiple projects? A: Yes, you can create multiple projects. Each project has its own settings (login, session) and tests.

Q: How do I organize my tests? A: Use descriptive test names, group related tests in the same project, and archive old tests. See Test Organization.

🔧 Troubleshooting

Browser Plugin Issues

Problem: Plugin won't authenticate

Solutions:

  1. Verify API key is correct (check for extra spaces)

  2. Ensure you copied the complete API key

  3. Try disconnecting and reconnecting

  4. Check that API key is active (not deleted)

  5. Refresh the plugin popup

Problem: Recording not starting

Solutions:

  1. Ensure you're on a valid webpage (not chrome:// pages)

  2. Refresh the page to reload content script

  3. Check browser console for errors

  4. Verify plugin is authenticated

  5. Try closing and reopening plugin popup

Problem: Steps not being captured

Solutions:

  1. Click elements directly (avoid keyboard shortcuts)

  2. Wait for page to fully load before recording

  3. Check if JavaScript framework is blocking events

  4. Review browser console for errors

  5. Try recording on a simpler page first

Test Execution Issues

Problem: Test stuck in IN_QUEUE

Solutions:

  1. Check Agents page for agent availability

  2. Verify at least one agent is connected

  3. Wait for agent to become available

  4. Restart agent if needed

Problem: Test stuck in RUNNING

Solutions:

  1. Wait a bit longer (test may still be executing)

  2. Check agent status (may have disconnected)

  3. Review execution logs for errors

  4. Cancel and re-run test if needed

Problem: All steps fail immediately

Solutions:

  1. Check that target URL is accessible

  2. Verify selectors are correct

  3. Check if page requires authentication

  4. Review error messages for specific issues

Selector Issues

Problem: Selector not found

Solutions:

  1. Verify element exists on page (use browser DevTools)

  2. Add WAIT step before interaction

  3. Update selector if page structure changed

  4. Use alternative selector if available

  5. See Troubleshooting Selectors

Problem: Selector matches multiple elements

Solutions:

  1. Add positional index: (//button[@class='submit'])[1]

  2. Use more specific selector

  3. Add parent anchor for context

  4. Use alternative selector

Problem: Selector breaks after page update

Solutions:

  1. Update to use ID or data-testid (more stable)

  2. Review page changes and update selector

  3. Use parent-based selector for stability

  4. Consider using selector repository

Login & Session Issues

Problem: Login flow fails

Solutions:

  1. Verify credentials in Project Settings → Login

  2. Check login URL is correct

  3. Review login test steps

  4. Update selectors if login page changed

  5. Test login manually first

Problem: Session validation always fails

Solutions:

  1. Clear session and create new one

  2. Update validation steps in login test

  3. Verify domain matches test URL domain

  4. Check confirmation element still exists

Problem: Full login happens every time

Solutions:

  1. Verify session was saved after first login

  2. Check session domain matches test domain

  3. Review validation steps in login test

  4. Clear and recreate session if needed

AI Generation Issues

Problem: Test generation stuck in DRAFTING

Solutions:

  1. Check agent availability

  2. Verify target URL is accessible

  3. Wait longer (generation can take 30-60 seconds)

  4. Check server logs for errors

  5. Try simpler prompt

Problem: No steps generated

Solutions:

  1. Improve prompt (be more specific)

  2. Verify target URL is accessible

  3. Check if LLM API is configured

  4. Review error messages on test page

  5. Try different prompt

Problem: Generated steps are incorrect

Solutions:

  1. Review and edit incorrect steps manually

  2. Improve prompt with more details

  3. Update selectors if needed

  4. Regenerate with better prompt

💡 Tips & Best Practices

Test Creation

  • Start with Recording: Browser plugin recording is the fastest way to create tests

  • Use Descriptive Names: Name tests clearly (e.g., "Login Flow - Valid Credentials")

  • Review Generated Steps: Always review AI-generated or recorded steps before running

  • Test Immediately: Run test right after creation to catch issues early

Selectors

  • Prefer IDs: Elements with IDs produce the best selectors

  • Use data-testid: Add data-testid attributes to important elements

  • Avoid CSS Classes: Classes change with styling updates

  • Review Selectors: Check generated selectors in test detail page

Session Management

  • Set Up Login Early: Configure login settings when you start testing authenticated flows

  • Monitor Session Reuse: Check if sessions are being reused (faster execution)

  • Clear When Needed: Clear sessions if authentication changes

  • Verify Domain Match: Ensure session domain matches test URL domain

Test Execution

  • Check Agent Status: Verify agents are available before running tests

  • Monitor Progress: Watch execution progress for issues

  • Review Results: Always review results after execution

  • Fix Issues Promptly: Update tests when selectors break

Debugging

  • Read Error Messages: Error messages provide specific information

  • Check Screenshots: Visual verification helps identify issues

  • Review Logs: Execution logs show what happened

  • Test Manually: Reproduce issues manually to understand them

📚 Additional Resources

Documentation

Learning Paths

For QA Engineers:

  1. Account Setup

  2. Browser Plugin Recording

  3. Running Tests

  4. Debugging Failed Tests

For Developers:

  1. Account Setup

  2. AI Test Generation

  3. XPath Selectors

  4. Performance Optimization

For Test Automation Teams:

  1. Core Concepts

  2. Session Management

  3. Test Organization

  4. All Tutorials

🔍 Common Error Messages

"Element not found" The selector doesn't match any element. Check selector, add WAIT step, or verify element exists.

"Selector matches multiple elements" Selector is too generic. Add positional index or use more specific selector.

"Timeout waiting for element" Element didn't appear in time. Increase timeout or add explicit WAIT step.

"No available agent" No agents are connected. Check agent status and ensure at least one is available.

"Login flow failed" Login test execution failed. Check credentials, review login test steps, update selectors.

"No session data found" No session exists for domain. Run test with login to create session, or check domain match.

See Error Codes Reference for complete list.

📝 Known Issues & Limitations

Current Limitations

  • API Not Available: Programmatic API is coming soon. Currently, use web interface.

  • Single Agent: Tests run on one agent at a time (parallel execution coming soon)

  • Manual Session Import: Session data must be imported manually (automation coming soon)

Browser Compatibility

  • Chrome Only: Browser plugin currently supports Chrome only

  • Manifest V3: Plugin uses Manifest V3 (latest Chrome extension standard)

Performance

  • Test Execution Time: Depends on page load times and network latency

  • AI Generation: Can take 30-60 seconds for complex tests

  • Session Validation: Adds 2-3 seconds to test execution

🆘 Still Need Help?

If you can't find the answer you're looking for:

  1. Search Documentation: Use the search function to find relevant articles

  2. Check Related Topics: Each help article links to related documentation

  3. Review Examples: See Tutorials for real-world examples

  4. Check Changelog: See Changelog for latest updates and fixes

Last updated: January 2025

Last updated