Sharedo Health Research

Autonomous Playwright-based inspector that logs into a target web app, captures network traffic, and generates endpoint documentation. Designed to discover auth mechanisms (bearer vs cookies), enumerate endpoints, and help plan automated health checks.

Quick Start

1. Copy .env.example to .env and adjust values (do not commit secrets):

cp .env.example .env

Key variables:

• TARGET_URL: start URL (e.g., the login page or app root).
• LOGIN_USERNAME, LOGIN_PASSWORD: credentials for form-based login.
• LOGIN_*_SELECTOR: CSS selectors for username, password, and submit; first match used.
• PAUSE_FOR_MANUAL_LOGIN: set to true for SSO/manual flows; inspector waits up to 5 minutes.
• HEADLESS: set false to watch the browser.
• CRAWL_MAX_PAGES: light same-origin crawl depth (default 10).
• CAPTURE_DURATION_SECONDS: continue capturing after crawl to catch background calls.

2. Install dependencies:

npm install
npx playwright install chromium

3. Run capture (headless) or headful:

npm run capture
npm run capture:headful       # forces a visible browser
npm run capture:quick            # 5s capture, minimal crawl
npm run capture:quick:headful    # same as above, with UI (forces visible browser)
npm run capture:login-demo       # 30s headful run w/ frequent screenshots to show login
npm run capture:observe          # 10m headful run; you drive the UI; we record

The run saves a JSON artifact to data/session-<timestamp>.json and a HAR to trace/network-<timestamp>.har.

4. Generate docs:

npm run analyze
npm run report:screens        # build HTML report with screenshots
npm run report:workflows      # build workflow diagnostics report from latest capture
AUTH_TOKEN=... WORKFLOW_ACTIVE_VIEW_ID=<uuid> npm run collect:workflows -- \
  --base https://demo-aus.sharedo.tech   # one-shot JSONL metrics
AUTH_TOKEN=... WORKFLOW_ACTIVE_VIEW_ID=<uuid> npm run collect:workflows:loop -- \
  --base https://demo-aus.sharedo.tech --interval 60   # run every 60s
node src/export_workflows_csv.js --date $(date +%F)   # export CSVs from JSONL
node src/collect_workflows.js --prom --base https://demo-aus.sharedo.tech  # print Prometheus metrics
node src/extract_viewids.js    # extract latest viewId(s) from a capture into data/viewIds.json

Outputs docs/endpoints-<timestamp>.md with an inventory and cURL examples (secrets redacted).

CLI Options

All .env options are also flags, e.g.:

node src/capture.js --url https://demo-aus.example.com/ --headless false --pauseManual true

Auth Notes

• The inspector redacts Authorization and cookie values at capture time.
• If bearer tokens are used, they typically come from a login exchange or refresh endpoint; consider short TTLs.
• If cookie-based auth is used, preserve session cookies and any CSRF tokens when reproducing calls.

Next Steps

• Add targeted navigation for known routes/components to exercise more endpoints.
• Build automated health checks using the generated inventory and auth pattern (bearer/cookie).
• Optionally, export HAR/JSON to your monitoring pipeline for synthetic checks.
• Use npm run report:screens to generate a browsable HTML report in docs/screenshots/session-<timestamp>/index.html with annotated screenshots and event engine stream stats summary. Headful vs headless precedence:
• CLI flag beats env: --headless false opens the browser even if .env has HEADLESS=true.
• Env precedence: HEADFUL=1 forces headful; otherwise HEADLESS=true makes it headless by default. Analyzer filters:
• --xhrOnly: include only XHR/fetch calls
• --methods=POST,PUT,PATCH,DELETE: restrict to CRUD
• --includeHealth: additionally include GET diagnostics/health endpoints (health, metrics, diagnostics, streamStats, status)

Convenience:

• npm run analyze:xhr-crud-health

Collectors:

• collect:workflows (HTTP mode): requires a bearer token and the Active Processes viewId.
  • Env: AUTH_TOKEN, WORKFLOW_ACTIVE_VIEW_ID, optional BASE_URL.
  • Flags: --base, --viewId, --token, --pageSize, --maxPlans.
  • Output: appends a JSONL line to data/metrics/workflows-YYYY-MM-DD.jsonl with streamStats summary, per-state totals, and enriched samples (type, steps, sample step duration).
• collect:workflows:loop: runs the collector on a fixed interval (seconds). Flags after -- are forwarded to collect:workflows.