rspade_system/app/RSpade/man/rsx_debug.txt

RSX:DEBUG - Route Debugging Tool
================================

OVERVIEW

rsx:debug is a comprehensive debugging tool that uses a headless Chromium browser
via Playwright to test routes, capture responses, monitor console output, inspect
DOM state, track XHR requests, and analyze logs. It provides complete visibility
into both server-side and client-side behavior.

This is a development-only tool that is disabled in production environments.

BASIC USAGE

    php artisan rsx:debug <url> [options]

Examples:
    php artisan rsx:debug /dashboard
    php artisan rsx:debug /api/users --no-body
    php artisan rsx:debug /login --full

CORE OPTIONS

--user=<id> | --user-id=<id>
    Test as a specific user ID, bypassing authentication. Uses backdoor
    authentication that only works in development environments.

--no-body
    Suppress HTTP response body output. Useful when you only want to see
    headers, status code, console errors, or other diagnostic information.

--full
    Enable all display options except --no-body and --follow-redirects.
    Provides maximum diagnostic information in a single command.

--timeout=<ms>
    Navigation timeout in milliseconds (minimum 30000ms, default 30000ms).
    Use for slow-loading pages or complex SPAs.

CONSOLE OUTPUT

--console
    Display all browser console output, not just errors. Shows console.log(),
    console.warn(), console.info(), and console_debug() output.

--console-log
    Alias for --console.

--console-debug-filter=<channel>
    Filter console_debug() output to a specific channel (e.g., AUTH, DISPATCH,
    BENCHMARK). Automatically enables console_debug and --console.

--console-debug-all
    Show all console_debug() channels without filtering.

--console-debug-benchmark
    Include benchmark timing prefixes in console_debug() output.

--console-debug-disable
    Disable console_debug() entirely for this test.

LOGS

--log
    Display Laravel error log if not empty.

--all-logs
    Display all log files: Laravel log and nginx access/error logs.

XHR/AJAX MONITORING

--xhr-list
    Show simple list of XHR/fetch requests with URLs and status codes only.

--xhr-dump
    Capture full details of XHR/fetch requests including headers, request
    payload, and response body.

DOM INSPECTION

--expect-element=<selector>
    Verify that an element exists by CSS selector. Command fails if element
    is not found. Useful for testing that critical UI elements render.

--dump-element=<selector>
    Extract and display HTML of a specific element by CSS selector.

--input-elements
    List all form input elements on the page with their values, attributes,
    and state.

--wait-for=<selector>
    Wait for a CSS selector to appear before capturing output. Useful for
    pages with async content loading or SPAs.

HTTP TESTING

--post=<json>
    Send POST request with JSON data instead of GET request.
    Example: --post='{"username":"test","password":"pass"}'

--follow-redirects
    Follow HTTP redirects and show the full redirect chain.

--headers
    Display all HTTP response headers.

--cookies
    Display all browser cookies with domains and expiry times.

BROWSER STATE

--storage
    Display localStorage and sessionStorage contents.

SCREENSHOTS

--screenshot-path=<path>
    Path to save screenshot file. Triggers screenshot capture with default
    width of 1920px and maximum height of 5000px.

--screenshot-width=<width|preset>
    Screenshot width in pixels or device preset name. Used with --screenshot-path.

    Available presets:
    - mobile          412px  (Pixel 7)
    - iphone-mobile   390px  (iPhone 12/13/14)
    - tablet          768px  (iPad Mini)
    - desktop-small   1366px (Common laptop)
    - desktop-medium  1920px (Full HD) - default
    - desktop-large   2560px (2K/WQHD)

    Examples:
        --screenshot-path=/tmp/page.png
            # Default 1920px width

        --screenshot-width=mobile --screenshot-path=/tmp/mobile.png
            # 412px mobile viewport

        --screenshot-width=1024 --screenshot-path=/tmp/custom.png
            # Custom 1024px width

JAVASCRIPT EVALUATION

--eval=<code>
    Execute JavaScript code in the page context and display the result.
    Useful for testing RSX JavaScript APIs or inspecting global state.

    Examples:
        --eval="Rsx.Route('Demo_Controller').url()"
        --eval="JSON.stringify(Rsx._routes)"
        --eval="typeof jQuery"
        --eval="document.title"

AUTHENTICATION & BACKDOOR

The --user and --user-id options use backdoor authentication that only works
in development/testing environments. The tool sends an X-Dev-Auth-User-Id
header that the framework recognizes and uses to authenticate as that user
without requiring login credentials.

This feature is:
- Only available in local/development/testing environments
- Automatically disabled in production
- Useful for testing protected routes
- Does not require modifying session state

ERROR HANDLING

The tool sends an X-Playwright-Test header that triggers plain text error
responses instead of HTML error pages. This provides cleaner error output
with full stack traces that are easier to debug.

Exit codes:
- 0: Success (status < 400, no console errors, no network failures)
- 1: Failure (status >= 400, console errors, or network failures)

OUTPUT FORMAT

The command outputs in a terse, parseable format:
- Status line with URL and HTTP status code
- Console errors (always shown if present)
- Console logs (if --console used)
- XHR/fetch requests (if --xhr-dump or --xhr-list used)
- Response headers (if --headers used)
- Response body (unless --no-body used)
- Laravel/nginx logs (if --log or --all-logs used)

PREREQUISITES

The tool automatically installs required dependencies:
- Node.js (must be pre-installed)
- Playwright npm package (auto-installed if missing)
- Chromium browser (auto-installed if missing)

LOG ROTATION

The tool automatically rotates development logs before and after each test
to ensure a clean slate. This means each test starts with empty logs and
only shows errors/output from that specific test run.

COMMON PATTERNS

Test a protected route as user ID 1:
    php artisan rsx:debug /admin/users --user=1

Check if JavaScript errors occur:
    php artisan rsx:debug /page
    # Console errors are always shown

Monitor all AJAX calls on a page:
    php artisan rsx:debug /dashboard --xhr-list

Debug a form submission:
    php artisan rsx:debug /api/save --post='{"name":"test"}' --xhr-dump

Verify critical elements loaded:
    php artisan rsx:debug /page --expect-element="#submit-button"

Check console_debug output for AUTH channel:
    php artisan rsx:debug /login --console-debug-filter=AUTH

Capture mobile and desktop screenshots:
    php artisan rsx:debug /page --screenshot-width=mobile --screenshot-path=/tmp/mobile.png
    php artisan rsx:debug /page --screenshot-width=desktop-large --screenshot-path=/tmp/desktop.png

IMPORTANT NOTES

• When using rsx:debug with grep and no output appears, re-run without grep
  to see the full context and any errors that may have occurred.

• Use rsx_dump_die() in your PHP code for temporary debugging output.

• This command is development-only and automatically disabled in production.

• The tool uses a real Chromium browser, so JavaScript executes exactly as
  it would for end users.

• For more details on console_debug: php artisan rsx:man console_debug
  For config options: php artisan rsx:man config_rsx

RELATED COMMANDS

php artisan rsx:routes       List all registered routes
php artisan rsx:ajax         Test Ajax endpoints directly
php artisan rsx:check        Run code quality checks

SEE ALSO

console_debug, config_rsx, routing