Running Tests

This guide explains how to execute tests in TrueAssert and understand the test execution process.

Overview

When you run a test:

1. A TestExecution is created with status IN_QUEUE

2. The controller's background processor picks up the test

3. Commands are queued for each test step

4. An available agent executes the commands

5. Results are reported back and displayed in real-time

Running a Test

From Test Detail Page

1. Navigate to the test detail page (Test Detail)

2. Ensure the test status is READY (not DRAFTING or REVIEW)

3. Click the "Run Test" button

4. The test execution begins immediately

What Happens

Immediate Actions:

• TestExecution object created with IN_QUEUE status

• TestStepExecution objects created for each step (status: PENDING)

• Test's last_execution field is updated

• Status changes to RUNNING when controller picks it up

Execution Process:

1. CLEAR_BROWSER command is queued first (clears browser state)

2. If login_required=True, login flow executes

3. If use_predefined_session=True, session is loaded

4. Test steps are executed in order

5. Each step execution updates status: PENDING → RUNNING → SUCCESS/FAIL

6. Test execution completes: RUNNING → SUCCESS/FAIL

Execution Status

Test Execution Status Flow

IN_QUEUE → RUNNING → SUCCESS/FAIL

Status Meanings:

• IN_QUEUE: Test is waiting to be picked up by controller

• RUNNING: Test is currently executing

• SUCCESS: All steps completed successfully

• FAIL: One or more steps failed

Step Execution Status Flow

PENDING → RUNNING → SUCCESS/FAIL/SKIPPED

Status Meanings:

• PENDING: Step is waiting to be executed

• RUNNING: Step is currently executing

• SUCCESS: Step completed successfully

• FAIL: Step failed (error message available)

• SKIPPED: Step was skipped (rare)

Monitoring Execution

Real-time Updates

The test detail page polls for status updates:

• Polling Interval: Every 2 seconds

• Status Badge: Updates automatically (RUNNING, SUCCESS, FAIL)

• Progress Bar: Shows completed steps / total steps

• Step Status: Each step shows its execution status

Execution Details

View detailed execution information:

1. Click on the execution status badge

2. Or navigate to Execution Detail

3. See:

   • All step results with status

   • Screenshots (if captured)

   • Error messages for failed steps

   • Execution logs

Command Queue System

How Commands Are Queued

1. TestExecutor creates Command objects for each step

2. Commands are added to CommandQueue

3. Commands include:

   • execution_id: Links to TestExecution

   • step_id: Links to TestStepExecution UUID

   • action_type: CLICK, FILL, GOTO, WAIT, etc.

   • selector: XPath or CSS selector

   • value: Input value (for FILL)

   • description: Human-readable description

Agent Assignment

1. Controller's background processor runs every 2 seconds

2. Finds tests with IN_QUEUE status

3. Assigns test to available agent

4. Agent polls for commands via gRPC

5. Agent executes commands and reports results

Execution Flow Details

Step 1: Test Execution Creation

When you click "Run Test":

execution = TestExecution.objects.create(
    test=test,
    triggered_by=request.user,
    status=TestExecution.Status.IN_QUEUE,
    test_version=test.version
)

Step 2: Step Executions Created

For each test step:

TestStepExecution.objects.create(
    test_execution=execution,
    test_step=step,
    status=TestStepExecution.Status.PENDING
)

Step 3: Commands Queued

TestExecutor queues commands:

1. CLEAR_BROWSER command (always first)

2. Login flow commands (if login_required=True)

3. Session load commands (if use_predefined_session=True)

4. Test step commands (in order)

Step 4: Agent Execution

Agent receives commands via gRPC:

1. Polls for next command

2. Executes command in browser (Selenium)

3. Reports result back via ReportResult RPC

4. Controller updates TestStepExecution status

Step 5: Completion

When all steps complete:

• TestExecution status → SUCCESS or FAIL

• Final screenshot captured (if enabled)

• Execution results saved

Login Flow During Execution

If login_required=True:

1. Session Validation (first attempt):

   • LOAD_SESSION command

   • Validation steps (GOTO + WAIT from login test)

   • If successful: Skip full login

2. Full Login (if validation fails):

   • CLEAR_BROWSER command

   • Execute all login test steps

   • SAVE_SESSION command

   • Session data saved to database

See Session Management for details.

Session Flow During Execution

If use_predefined_session=True:

1. Load session data for project's domain

2. LOAD_SESSION command with session data

3. Navigate to target URL

4. Execute test steps

Error Handling

Failed Steps

When a step fails:

• Step status → FAIL

• Error message stored in TestStepExecution

• Screenshot captured (if enabled)

• Test continues with next step (unless critical failure)

Test Failure

Test fails if:

• Login flow fails (when login_required=True)

• Session load fails (when use_predefined_session=True)

• Critical step fails (depends on test configuration)

Common Errors

"No available agent":

• No agents are connected

• All agents are busy

• Check Agents page for agent status

"Test is already running":

• Previous execution still in progress

• Wait for current execution to complete

• Or cancel previous execution

"Selector not found":

• Element doesn't exist on page

• Selector is incorrect

• Page structure changed

Execution Logs

Viewing Logs

1. Go to test detail page

2. Click on execution status

3. View step-by-step execution results

4. Check error messages for failed steps

Screenshots

Screenshots are captured:

• After each step (if enabled)

• On step failure (automatic)

• At test completion

View screenshots:

• In execution detail page

• Click on step result

• Screenshot URL: Screenshot

Best Practices

Before Running

1. Verify Test Status: Ensure test is READY

2. Check Agents: Verify agents are available

3. Review Steps: Check that all steps are correct

4. Verify Selectors: Ensure selectors are valid

During Execution

1. Monitor Progress: Watch status updates

2. Check Logs: Review execution logs if issues occur

3. Wait for Completion: Don't run test again while executing

After Execution

1. Review Results: Check all step results

2. Analyze Failures: Read error messages

3. Check Screenshots: Visual verification of steps

4. Fix Issues: Update selectors or steps as needed

Troubleshooting

Test Stuck in IN_QUEUE

Possible Causes:

• No agents available

• Controller background processor not running

• Agent connection issues

Solutions:

• Check Agents page for agent status

• Verify controller is running

• Restart agent if needed

Test Stuck in RUNNING

Possible Causes:

• Agent crashed or disconnected

• Command execution timeout

• Browser hang

Solutions:

• Check agent logs

• Restart agent

• Check for browser issues

Steps Not Executing

Possible Causes:

• Commands not queued properly

• Agent not receiving commands

• Selector issues

Solutions:

• Check command queue status

• Verify agent is polling

• Review selector validity

Related Topics

• Viewing Results - Understand execution results

• Debugging Failed Tests - Fix test failures

• Session Management - Handle authentication

• Your First Test - Create and run your first test

---

← Back to Documentation | Next: Viewing Results →