Futuristic Webload Technical Help

You can read the entire documentation and learn how to use Futuristic Webload manually. To help you work better and faster, we prepared an MD text specifically optimized for your AI agents.

Feed your AI with this text, and ask it what you need: CLI syntax, environment variables, CI/CD scripts, error code detection, or Captcha bypass integration.

Loading AI Agent Specification...

Futuristic Webload is a deterministic browser replay engine built for load testing, run analytics, and repeatable QA. You record once, harden the script, and then replay it at scale (locally, on-prem sharded, or in cloud).

What You Install (Download Package)

The local package includes the core CLIs:

• load-test.exe - record/replay engine + visual editor (UX).
• runs-manager.exe - local UI for browsing artifacts + database import.
• shard-run.exe - on-prem sharding wrapper that launches load-test.exe across nodes consistently.

Check the Installed Version

Both primary client applications support --version. Run the command from the folder containing the executable:

load-test.exe --version
runs-manager.exe --version

Each command prints the semantic product version and exits without starting the application. For example:

Futuristic WebLoad Load Test 1.0.0
Futuristic WebLoad Runs Manager 1.0.0

The product version identifies the release shared by the client applications and installers. It is separate from the build/package ID used to identify a particular published artifact.

The Full Workflow (Record - Approve - Run - Analyze)

1. Record (Create the Script)

Start the UX and record a real browser session. The output is a deterministic script file: recording.json.

2. Approve & Harden (Editor / UX)

Open the recording in the visual editor and harden it before scaling:

• Review steps and selectors (deterministic: 0 matches or >1 matches fails fast).
• Attach a databank (user parameters) and replace hard-coded values with valueFromUser bindings.
• Add snapshot points for debugging (DOM / screenshot / trace / network) where needed.

3. Prepare the Run Plan (Local / On-Prem / Cloud)

Choose how you want to run and what you want to collect. The UX helps you generate correct CLI commands for your plan.

• Local runs: run one machine with load-test.exe -replay for debugging and small load.
• On-prem sharded runs: use shard-run.exe to distribute users across multiple nodes/VMs.
• Cloud runs: run the same script in managed cloud workers (domain ownership is required for protected environments).

4. Replay (Run the Load)

Start with a single user, then scale up:

// Single-user sanity check
load-test.exe -replay recording.json -runXUser 1

// Scale locally
load-test.exe -replay recording.json -runXUser 50 -recycleUsers

5. Data Collection (What Gets Captured)

During replay, the engine writes a stable artifacts tree under -outDir (per-user results, per-user summary, snapshots, and aggregate summary). Runs-Manager reads this tree and builds interactive analysis.

6. Reports (Interactive Analysis)

Runs-Manager provides interactive reports over your artifacts, including:

• Network call summaries and timing breakdowns (grouped by domain/path).
• Step execution summaries and diagnostics (including selector resolution issues).
• Frontend error summaries (captured JS errors).
• Vitals/runtime metrics when enabled.

7. Import to SQL (Optional)

If you need long-term retention and dashboards, use Runs-Manager import mode to load TSV datasets into MySQL / MSSQL / Oracle. The UX also guides you through selecting datasets and mapping table names.

Cloud Run Prerequisite: Domain Ownership

Cloud runs may require domain ownership validation for protected environments. The domain proof flow uses a short-lived token and can be verified via a /.well-known HTTP proof file path.

On-Prem Notes (Sync Points)

runs-manager.exe is a local UI + API service (ASP.NET / Kestrel) for browsing run artifacts, coordinating local orchestration helpers, importing run datasets into your database, and exporting CI/CD aggregates from the same report tree.

Runs-Manager is local-only. Even if you bind a non-loopback URL via --urls, it rejects any request that does not originate from the local machine (loopback) with 403. Runs-Manager reports are available only on localhost. If you need report access on your network, contact us for a network-accessible deployment.

1. Local UI + Control API

Runs-Manager serves a browser UI and local APIs for inspecting results and managing local workflows. You can control its binding via standard ASP.NET hosting arguments:

• Default Binding: http://127.0.0.1:5057
• Port Override: runs-manager.exe --urls "http://127.0.0.1:8080"
• Main UI: http://127.0.0.1:5057/UX/index.html
• Reports: http://127.0.0.1:5057/UX/reports.html?WebLoadDir=<folder>
• Open UI: navigating to / redirects into the UX pages.

2. Database Import Engine (The DevOps "One-Shot")

Designed for CI/CD pipelines, this mode ingests run datasets (TSV and snapshot metadata) into your database with a single command. Supported databases: mysql, mssql, oracle.

runs-manager.exe --noUX --ImportToDatabase `
  --Database mysql `
  --ConnectionString "server=localhost;user=root;password=...;database=fwl_results" `
  --WebLoadDir "C:\Runs\run-001" `
  --TableConflictPolicy FailAllOnAnyBlockedTable `
  --RuntimeErrorPolicy StopOnFirstDatasetError

Import CLI Flags (Implemented)

TableMappingsJSON Example

Map specific dataset filenames to your own table names. Any dataset not mapped uses a default FWL_<dataset> table name.

runs-manager.exe --noUX --ImportToDatabase `
  --Database mysql `
  --ConnectionString "server=localhost;user=root;password=...;database=fwl_results" `
  --WebLoadDir "C:\Runs\run-001" `
  --TableMappingsJSON "{\"http_report.tsv\":\"Production_Traffic_Logs\",\"steps_report.tsv\":\"QA_Test_Steps_Historical\"}"

SelectedDatasetsJSON Example

Import only a subset of datasets:

runs-manager.exe --noUX --ImportToDatabase `
  --Database mysql `
  --ConnectionString "server=localhost;user=root;password=...;database=fwl_results" `
  --WebLoadDir "C:\Runs\run-001" `
  --SelectedDatasetsJSON "[\"http_report.tsv\",\"steps_report.tsv\",\"js_errors.tsv\"]"

Default Tables Created (Expandable)

When you do not pass --SelectedDatasetsJSON, Runs-Manager attempts a default dataset set. For each dataset, it creates (or expects) a table named FWL_<dataset> unless overridden by --TableMappingsJSON.

Advanced Import Logic

3. Auditability & Correlation

Every row imported into your database is enriched with metadata for easy correlation with CI/CD build IDs:

• import_batch_id: A high-precision timestamp (yyyyMMddHHmmssfff) representing the ingestion session.
• source_file_rel: Tracks exactly which shard or worker produced the data.
• source_row_no: Enables deep-diving back to the original local TSV log for debugging.

User preferences: Runs-Manager user preferences are written under %LocalAppData%\FuturisticWebLoad\runs-manager\UserPreferences\.

4. Headless CICD Aggregate Export

Runs-Manager also exposes a headless CI/CD path that reads the existing report tree, computes aggregates, and emits machine-readable results for scripted checks.

• Primary switch: --EmitAggregates
• Report root: --ReportsRoot <path>
• Rules file: --RulesFile <rules.json>
• Formats: console, json, or tsv
• Optional outputs: --OutFile, --Datasets, --MaxRows, --FailOnMatch, --FailOnViolation

If you do not pass --Format, Runs-Manager defaults to json.

The rules JSON is a small, versioned criteria file that tells Runs-Manager what to inspect and what to report. It is not a free-form query language. Each rule describes:

• Which dataset to inspect, such as calls, steps, syncpoints, users, summary, or customReports.
• How to match rows, using patterns like URL, path, step name, run id, or custom field filters.
• Which aggregate to compute, such as count, sum, avg, min, max, std, p50, p90, p95, or p99.
• How to compare the computed value against a threshold, using operators like gt, gte, lt, lte, eq, neq, or between.
• What severity to use when a rule matches, such as info, warn, or fail.

customReports rules are discovery rules with a few extra fields: reportNamePattern, scope (snapshot, run, runUser), mode (count, missing, histogram), expected (allUsers, allRuns, allSnapshots, count), valueSource (content, line, field), valueTransform (raw, normalize, hash), plus optional filters like matchRunIdPattern, matchSnapshotIdPattern, matchUserPattern, and optional flags like emitMissingUsers and emitHistogram. When valueSource is field, the rule can also set valueFieldName. expected controls the coverage shape: allUsers counts distinct run/user pairs, allRuns counts distinct runs, allSnapshots counts distinct snapshot instances, and count uses expectedCount when supplied or falls back to the number of matching candidates.

If the rules file is missing, the exporter can still run and emit a plain summary. If the rules file exists, the exporter evaluates the criteria and emits matching rule rows plus the summary envelope.

{
  "version": 1,
  "defaultAction": "allow",
  "rules": [
    {
      "id": "invoice-p95-high",
      "dataset": "calls",
      "match": {
        "urlPattern": ".*/invoice/.*"
      },
      "aggregate": {
        "fn": "p95",
        "field": "TotalMs"
      },
      "compare": {
        "op": "gt",
        "value": 1000
      },
      "severity": "fail",
      "emit": true
    }
  ]
}

runs-manager.exe --EmitAggregates `
  --ReportsRoot "C:\Build\Run-42" `
  --RulesFile "C:\Build\run-rules.json" `
  --Format json `
  --OutFile "C:\Build\run-42-aggregates.json"

This path does not start the UI and does not open a browser. It is meant for CI checks, scripted regression gates, and small machine-readable summaries from existing run artifacts.

shard-run.exe is a specialized wrapper designed for Massive Scale. It abstracts the complexity of manually calculating user offsets and slot IDs across a cluster of VMs.

shard-run.exe -shard shards.json -input input.zip -shard-id 1 -- -withUX

1. Shards Configuration (shards.json)

This file defines the workload distribution and output layout. It is typically generated by your CI/CD pipeline (Jenkins/GitHub Actions) or a master orchestrator.

{
  "cloudTaskKey": "your-cloud-task-key",
  "outRoot": "C:\\Runs\\Out",
  "orchestrationServer": "http://127.0.0.1:5057",
  "recycleUsers": true,
  "shards": [
    {
      "shardId": 1,
      "runGroupId": 1,
      "userStart": 1,
      "usersInShard": 50,
      "outDirRelative": "run-1"
    }
  ]
}

2. CI/CD Orchestration Contract

When Shard-Run executes, it enforces a standard environment contract so results are grouped and correlated consistently:

• FWL_CLOUD_TASK_KEY: Copied from shards.json into the child process environment.
• FWL_RUN_ID: Set to run-<runGroupId> (example: run-3).
• RUN_SLOT: Set to the same value as FWL_RUN_ID for compatibility (run-<runGroupId>).
• FWL_RECYCLE_USERS: 1 when recycleUsers is enabled in shards.json, otherwise 0.

3. What Shard-Run Actually Launches

Under the hood, Shard-Run executes load-test.exe in replay mode using zip input, sets -runXUser based on usersInShard, and starts databank selection from userStart (1-based). Output goes to outRoot\\outDirRelative (or defaults to outRoot\\run-<runGroupId>).

The core load-test.exe engine is built for reliability. When multiple inputs exist, the engine follows a simple rule: CLI flags override environment-variable fallbacks. The recorded JSON remains the replay contract, and specific replay flags (like -baseUrlOverride) may override specific values explicitly.

1. Installation & Package Choice

Choose the package that matches how you want to run Futuristic Webload:

• Light: smaller download; Chromium is downloaded automatically on first use.
• Offline: larger download; Chromium is included in the package.

No separate Chromium install step is required for the Windows desktop packages. If you deploy load-test or another browser worker onto your own machine, VM, or custom image, include the Chromium and OS dependencies in that environment before you run tests.

2. Base Commands

3. Replay & Orchestration Options

These flags control the concurrency, speed, and behavior of the browser workers.

4. Advanced Orchestration (Internal Contracts)

Used primarily by shard-run or cloud orchestrators to manage sync points and distributed state.

5. Vitals & Metrics Tuning

Control the overhead of telemetry collection for massive scale runs.

6. The Deterministic Engine

Futuristic Webload differs from traditional tools by keeping replay deterministic: the engine executes the recorded steps in order, and it does not "self-heal", retry, or make AI-like decisions during replay. If a selector resolves to zero elements (or multiple elements), replay fails fast so you can fix the script or the environment instead of masking the issue.

Sync Points

In distributed runs, workers can be configured to "Wait for Go" at specific steps. This allows you to coordinate 10,000 users to click "Submit" at the exact same millisecond, creating a true peak-load spike.

7. Environment Fallbacks

8. Practical Examples

Multi-Environment Testing

Run the same recording.json against different environments without modifying the script:

// Test against Staging
load-test.exe -replay recording.json -baseUrlOverride "https://staging.myapp.com"

// Test against Production
load-test.exe -replay recording.json -baseUrlOverride "https://prod.myapp.com"

Extreme Load Optimization (10k+ Users)

When scaling to massive numbers, disable all heavy telemetry to minimize node CPU/RAM usage:

load-test.exe -replay recording.json -runXUser 200 -noVitals -noBrowserSnapshot

Longevity & Soak Testing

Keep the load constant by recycling databank users indefinitely:

load-test.exe -replay recording.json -runXUser 50 -recycleUsers

Headful Debugging

Watch exactly what the browser is doing during a failure (headful mode):

load-test.exe -replay recording.json -withUX -replaySpeed 0.5

Using External Databanks

Inject a fresh dataset without touching your main script file:

load-test.exe -replay recording.json -databankFile "prod_users.json" -useDatabank random

Replay From a Zip Bundle (Advanced)

If you received a zipped bundle (for example from a CI artifact), you can replay directly from the zip. The tool extracts the zip and searches for recording.json inside it.

load-test.exe -zipInput "C:\Artifacts\run-bundle.zip"

1. Folder Layout (Typical)

When you set -outDir, the run output is written under a stable Runs/ tree. In cloud runs, you may have multiple run-N folders under a single task directory.

<runRoot>/
  recording.json
  Runs/
    Summary/
    User1/
      Results/
      Summary/
      Snapshots/
        Snapshot-Final/ (optional)

2. Per-User Results

These are the primary “debug” artifacts for failures and selector issues:

• Runs/UserN/Results/steps_report.tsv - per-step execution rows. startUtc is an ISO-8601 UTC timestamp; rows also contain action, duration, selector/value, and error fields.
• Runs/UserN/Results/http_report.tsv - per-request HTTP call log (status, timings, bytes, error).
• Runs/UserN/Results/http_grouped.tsv - aggregated HTTP summary grouped by URL key.
• Runs/UserN/Results/page_snapshot.html - human-readable page snapshot with scripts stripped, useful for quickly identifying page state.
• Runs/UserN/Results/page_visible_detail.html - transformed visible-elements page detail with computed styles, bounding rects, and visibility signals.
• Runs/UserN/Results/dom_summary.json, interactive_map.json, visible_text.json - compact AI-friendly page sidecars for page state, actionable controls, and visible text.
• Runs/UserN/Results/console.out.txt, console.err.txt, console.debug.txt - browser console streams.
• Runs/UserN/Results/sync_users_report.tsv - syncpoint coordination rows (when syncpoints are used).

3. Per-User Summary

These summarize the run and optional telemetry (file presence depends on flags/features used):

• Runs/UserN/Summary/script_summary.txt - high-level run summary.
• Runs/UserN/Summary/http_summary.txt - compact HTTP summary.
• Runs/UserN/Summary/http_timing_report.tsv - timing distributions.
• Runs/UserN/Summary/step_execution_diagnostics.tsv - selector/step resolution diagnostics.
• Runs/UserN/Summary/js_errors.tsv - JavaScript error rows.
• Runs/UserN/Summary/*vitals*.tsv, *runtime_metrics*.tsv - vitals/runtime sampling (when enabled).
• Runs/UserN/Summary/file_uploads.tsv, downloads.tsv - upload/download audit rows (when present).

4. Snapshots

If snapshots are enabled/created, each snapshot folder can include page-inspection, network, screenshot, and trace artifacts for a specific moment in the run.

• Runs/UserN/Snapshots/<SnapshotId>/screenshot.png - snapshot image (if enabled).
• Runs/UserN/Snapshots/<SnapshotId>/trace.zip - Playwright trace bundle (if enabled).
• Runs/UserN/Snapshots/<SnapshotId>/page_snapshot.html, page_visible_detail.html, dom_summary.json, interactive_map.json, visible_text.json - page-inspection artifacts at snapshot time (if enabled).
• Runs/UserN/Snapshots/<SnapshotId>/*.tsv - snapshot-level network/vitals/metrics (when enabled).

5. Aggregate Summary

Aggregate outputs live under Runs/Summary/ and summarize the entire run (all users):

• Runs/Summary/script_summary.txt
• Runs/Summary/http_summary.txt
• Runs/Summary/http_report.tsv (aggregated grouped report)
• Runs/Summary/steps_report.tsv (action totals)

6. Loading Into Runs-Manager (Manual)

Runs-Manager loads results from a webLoadDir folder. It discovers any directory named Runs under that folder (recursive). Practical options:

• Point Runs-Manager at a single run folder (that contains Runs/).
• Point Runs-Manager at the Runs/ folder itself.
• For Cloud Runs tasks, point it at the parent task folder and select the specific run-N inside the UI.

1. Policy

The client software requires a valid Software License. Without it, headless runs will not start and the UX will prompt you to license.

2. Binding Mode (User vs Machine)

• Machine license: Best for CI/CD agents or shared runners where many people use the same machine.
• User license: Best when one person uses Futuristic Webload across multiple machines under the same username.

3. Offline / On-Prem Usage

Licenses can be uploaded for offline work. License files are stored under:

%LocalAppData%\FuturisticWebLoad\Licenses\

New license writes go to LocalAppData. Legacy copies under <app-root>\Licenses may still be read for compatibility. You can copy the license files to another machine for on-prem runs. They remain valid as long as the license binding matches (computer name for machine-bound, username for user-bound).

4. Issuing for Remote Machines

You can issue a license for a remote computer in the management console, then upload it to the offline application or place it under %LocalAppData%\FuturisticWebLoad\Licenses\ on the target machine.

5. Local Run License (On-Prem Runs)

For local/on-prem replay, a short-lived local run license is prepared by Runs-Manager and written next to your script so it can be zipped and executed on another machine.

• Written under the script folder: .\Licenses\localrun.license.json and also .\license\localrun.license.json.
• Default validity: 12 hours (expiresInMinutes = 12 * 60).
• Required: without a software license or a valid local run license, the clients will not run.

1. What It Is

Some environments block automation by requiring a trusted client certificate before the app can be used. Futuristic Webload can replay runs with a client certificate injected into the browser handshake, so your test traffic is treated as "allowed" traffic.

2. Certificate Format (PEM)

The certificate must be provided as a PEM file. The replay runtime loads it from the path configured in your recording.json and injects it only for the configured origin.

3. Where the PEM File Lives

Use a relative path in the JSON whenever possible. The runtime resolves relative paths from the folder that contains the script file.

• Local replay: keep the PEM next to recording.json (or under a subfolder like ./Certs/).
• Zip / sharded / cloud replay: include the PEM inside the same zip bundle as recording.json so worker nodes can resolve it after extraction.

4. Operational Guidance

• Short-lived certs: issue a certificate with a short validity window and rotate it regularly.
• Ownership: you (the customer) are responsible for issuing and managing the certificate and any trust chain required by your environment.

5. Certificate Bypass Integration Snippet

Select your backend stack and copy/paste the integration snippet for validating incoming client certificates.

6. Futuristic Captcha Bypass (License Token)

In addition to certificate-based access, Futuristic Webload can pass a signed bypass token to your backend (if your system supports it). Tokens can be provided via:

• CLI flag -captchaBypassLicense
• Environment variable FWL_CAPTCHA_BYPASS_LICENSE
• Local license file at ./Licenses/FWL_CAPTCHA_BYPASS_LICENSE.txt

Backend Integration Snippet

Select your backend stack and copy/paste the integration snippet. (More stacks will be added over time.)

Futuristic Webload has two parts: a yearly software license for local/on-prem usage, and tokens for cloud/runtime consumption.

1. Software License

The software license covers local and on-prem replay workflows, including interactive reports.

• Price: $99 / year (choose user or machine licensing)
• Machine license: Ideal for CI/CD agents or shared runners where many people use the same machine.
• User license: Ideal when one person uses Futuristic Webload across multiple machines under the same username.
• Trial: Free trial available (see your download/activation flow).

2. Tokens (Cloud Runs + AI)

Tokens are the usage currency for services that have infrastructure and provider costs.

• Token price: $0.05 per token
• Cloud Runs: 1 token = 2 minutes of script runtime
• AI Usage: You set a budget CAP before execution so you control spend up-front.

Q: Why does the browser say "Not Secure" during certificate replay?

Playwright uses an internal TLS proxy to inject your Client Certificate into the handshake. This triggers a standard browser warning because the proxy uses a self-signed cert for the local intercept. Your connection to the actual server is secure, and the certificate is passing correctly.

Q: Why did my captcha bypass fail even though the license was active?

The bypass only works after replay reaches the captcha event and arms the header. If the protected click happens first, that request goes out without X-FWL-Captcha-Bypass. Move the captcha step earlier in the recording, or make sure the bypass event fires before the protected request.

Q: How do I handle 10,000+ concurrent users?

Use shard-run.exe to distribute the load across multiple VM nodes. We recommend max 100-200 users per node depending on your CPU/RAM specs.

Q: How do I use WebLoad to test my rate limits?

Record the normal user flow that hits the endpoint, then replay it with -runXUser to raise concurrency. Use -recycleUsers when you want sustained pressure from a smaller identity pool, and start low before increasing the user count in steps. Watch the reports for 429, 403, and 503 spikes, grouped by endpoint. For cleaner throughput testing, use -noBrowserSnapshot and -noVitals.

Q: Does the AI see my source code?

No. By default, the AI only has access to the run artifacts (TSVs, logs, screenshots). It does not access your source code or internal network unless you explicitly grant read-only folder access via the Runs-Manager settings.

Q: How do I disable all logs for peak performance?

Use the -noVitals and -noBrowserSnapshot flags. This minimizes disk I/O and CPU overhead during massive load tests.