Core Concepts

Understanding the fundamental concepts of TrueAssert will help you use the platform effectively.

Architecture Overview

TrueAssert consists of three main components:

  1. Django Web Platform (qa_platform/) - User interface and test management

  2. Agent Controller (controller/) - Test orchestration and agent management

  3. Browser Agent (agent/) - Selenium-based browser automation

Key Concepts

Tests

A Test represents an automated test case that can be executed against a web application.

Test Properties:

  • Name: Descriptive name for the test

  • Target URL: The website URL to test

  • Status: Current state (DRAFTING, REVIEW, READY, ARCHIVED)

  • Project: Belongs to a project (which belongs to an organization)

  • Version: Increments when test steps are modified

  • Login Required: Whether the test needs authentication

  • Use Predefined Session: Whether to reuse existing session data

Test Status Flow:

DRAFTING → REVIEW → READY
                ↓
            ARCHIVED

Test Steps

A Test Step is a single action in a test (e.g., click a button, fill a form, wait for an element).

Step Properties:

  • Action Type: CLICK, FILL, GOTO, WAIT, etc.

  • Selector: XPath or CSS selector to locate the element

  • Selector Type: XPATH or CSS

  • Value: Input value (for FILL actions)

  • Description: Human-readable description

  • Order: Sequence number in the test

Organizations

An Organization is the top-level container for grouping related work.

Organization Properties:

  • Name: Organization name

  • Owner: User who created the organization

  • Members: Users with access to the organization

  • API Keys: Belong to organizations

Default Setup: When you create an account, a "Default organization" is automatically created.

Projects

A Project belongs to an organization and groups related tests.

Project Properties:

  • Name: Project name

  • Organization: Parent organization

  • Base URL: Default URL for tests in this project

  • Login Settings: Optional login configuration (URL, username, password)

  • Session Data: Stored browser sessions (cookies, localStorage, sessionStorage)

Default Setup: A "Default project" is created automatically with your account.

API Keys

API Keys authenticate agents and browser plugins with TrueAssert.

Key Properties:

  • Name: User-friendly identifier

  • Organization: Belongs to an organization

  • Key Format: tp_[random_string]

  • Active Status: Can be revoked

  • Shared: One key can be used by multiple agents/plugins

Security: Keys are hashed (SHA-256) in the database. The plain text key is shown only once after creation.

Agents

Agents are browser automation workers that execute tests.

Agent Properties:

  • Name: Identifier for the agent

  • API Key: Authentication key

  • Status: Current state (IDLE, BUSY, etc.)

  • Organization: Belongs to an organization

How They Work:

  • Agents connect via gRPC

  • They poll for commands from the controller

  • Execute browser automation using Selenium

  • Report results back to the controller

Test Executions

A Test Execution represents a single run of a test.

Execution Properties:

  • Test: The test being executed

  • Status: IN_QUEUE, RUNNING, SUCCESS, FAIL

  • Triggered By: User who started the execution

  • Test Version: Version of the test when executed

  • Step Results: Individual step execution results

Execution Status Flow:

IN_QUEUE → RUNNING → SUCCESS/FAIL

Test Step Executions

A Test Step Execution represents the execution of a single test step.

Step Execution Properties:

  • Test Execution: Parent execution

  • Test Step: The step being executed

  • Status: PENDING, RUNNING, SUCCESS, FAIL, SKIPPED

  • Screenshot: Optional screenshot after execution

  • Error Message: Error details if failed

How Test Creation Works

Browser Plugin Recording

  1. User clicks "Record" in browser plugin

  2. Content script captures DOM events (clicks, keypresses)

  3. Actions are sent to service worker

  4. Service worker sends data to TrueAssert backend via Connect-ES

  5. Test is created with recorded steps

  6. XPath selectors are generated automatically

AI Test Generation

  1. User submits test creation form with prompt

  2. Test is created with status DRAFTING

  3. Background processor picks up the test

  4. TestGenerator uses LLM to analyze prompt

  5. LLM generates test steps based on prompt

  6. Steps are created and test status updates to REVIEW

  7. If login_required=True, login flow executes automatically

  8. Test status becomes READY when complete

Manual Test Creation

  1. User creates test via web interface

  2. User manually adds test steps

  3. User configures each step (action, selector, value)

  4. Test is ready when user marks it as READY

How Test Execution Works

  1. User Triggers Execution: Clicks "Run Test" in web interface

  2. Test Execution Created: TestExecution object created with IN_QUEUE status

  3. Step Executions Created: TestStepExecution objects created for each step

  4. Controller Picks Up Test: Background processor finds tests in queue

  5. Agent Assignment: Controller assigns test to available agent

  6. Status Updates: TestExecution status changes to RUNNING

  7. Commands Queued: Commands are added to command queue for each step

  8. Agent Executes: Agent polls for commands and executes them

  9. Results Reported: Agent reports results back via gRPC

  10. Status Updates: Step executions and test execution status updated

  11. Completion: Test execution marked as SUCCESS or FAIL

Session Management

Login Flow

When login_required=True:

  1. Session Validation: First tries to validate existing session

    • Executes LOAD_SESSION command

    • Runs validation steps (GOTO + WAIT from login test)

    • If successful, reuses session

  2. Full Login: If validation fails or no session exists

    • Executes CLEAR_BROWSER command

    • Runs all login test steps

    • Executes SAVE_SESSION command

    • Saves session data to database

Session Data

SessionData model stores browser state:

  • Cookies: All browser cookies

  • localStorage: Browser localStorage data

  • sessionStorage: Browser sessionStorage data

  • Domain: Per-domain session storage

  • Project: OneToOne relationship with Project

Selectors

XPath Selectors

TrueAssert generates intelligent XPath selectors that are more robust than CSS selectors.

Selector Priority (lower penalty = better):

  1. ID (penalty: 0)

  2. data-testid (penalty: 1)

  3. ARIA attributes (penalty: 5)

  4. Form attributes (penalty: 10)

  5. Text content (penalty: 20)

  6. CSS classes (penalty: 50)

  7. Structural positioning (penalty: 1000+)

Benefits:

  • More stable than CSS selectors

  • Resists UI changes better

  • Algorithmic generation ensures uniqueness

Selector Types

  • XPATH: XPath expression (e.g., //button[@id='submit'])

  • CSS: CSS selector (e.g., button#submit)

Communication Protocols

Connect-ES

Browser plugin uses Connect-ES (modern RPC framework) to communicate with the backend:

  • Endpoint: /connect/agent.AgentService/[method]

  • Protocol: HTTP-based RPC

  • No proxy needed (unlike old gRPC-Web/Envoy setup)

gRPC

Agents use gRPC for communication:

  • Protocol: gRPC over HTTP/2

  • Port: 50051 (default)

  • Methods: Register, Heartbeat, GetCommand, ReportResult

Background Processing

Test Generation

The BackgroundProcessor runs continuously:

  • Checks for tests with DRAFTING status

  • Processes tests one at a time

  • Uses TestGenerator to create steps

  • Updates test status as it progresses

Test Execution

The Controller manages test execution:

  • Polls for tests in IN_QUEUE status

  • Assigns tests to available agents

  • Manages command queue

  • Processes execution results

Related Topics

← Back to Getting Started

PreviousInstallationNextYour First Test

Last updated