System Architecture & Zero-Backend Engine
Opens as an isolated 960 × 750px window via chrome.windows.create(popup). Controls target browser tabs via message passing without injecting heavy UI frames into target websites.
Operates with dual-tier state persistence (chrome.storage.session & chrome.storage.local). Survives browser service worker suspension and rehydrates execution seamlessly.
Recorded workflows, test suites, and cryptographic keys remain strictly on your local device. FlowMacro does not operate any remote database, proxy servers, or third-party telemetry beacons.
Manifest V3 Permission Declarations:
activeTab & tabs: Attaches recorder/replayer content scripts into the specific tab you target.scripting: Dynamically injects recorder.js and replayer.js upon page navigation.storage & session: Persists your test suites and active recording heads locally across reloads.webNavigation: Detects top-level redirects and hash transitions (#/factor-one) to re-attach listeners.Quick Start: Your First Automation in 60s
Click the FlowMacro icon in your Chrome toolbar or hit Alt + Shift + R. The standalone controller window launches and establishes connection with your browser tab.
Enter your target starting URL in the BASE_URL field and click Record. Navigate and click elements naturally. Actions stream into the table in real time.
Hit Stop when finished. Click Replay Macro to test execution at 0.5x, 1x, or 2x speed. Export to Playwright (TS), Puppeteer (JS), or Python Selenium.
The 5-Tier Selector Waterfall & DOM Piercing
Most web recorders fail in production because they rely on fragile CSS selectors like div.css-19f8x > button.btn-3a. FlowMacro resolves this with an intelligent multi-tier locator hierarchy evaluated at capture time:
Open Shadow DOM Piercing (composedPath)
Uses composedPath() and recursive shadow host inspection. When an element lives inside a Web Component shadow root, FlowMacro emits deep piercing locators like shadow=host-component >>> inner-button.
QA & Test Attributes (data-testid)
Checks for data-testid, data-test, data-cy, and data-qa. Resilient against any styling or DOM tree redesign.
Semantic ID Filter (Regex Discard Engine)
Employs regex filters to eliminate autogenerated framework IDs like :r0: (React 18), ember1284, radix-id-12, and 4+ digit numeric hashes, preserving only stable IDs like #identifier-field.
Semantic ARIA & Accessible Roles
Captures [aria-label="Sign In"], [role="button"], and input [placeholder="..."].
Semantic Element & Button Text
Generates text-based locators such as xpath=//button[normalize-space()="Continue"] or css=button[type="submit"].
Sanitized CSS & Structural XPath Fallback
Generates hierarchical CSS with automatic emoji stripping (removing Clerk's .🔒️ classes) and standard structural XPath as a final resilience layer.
frameId from message senders. Commands recorded inside embedded payment frames (Stripe, PayPal) dispatch directly into the matching frame during replay.Zero-Trust Credential & Secret Vault
Hardcode plain-text passwords into exported JSON files or scripts. Committing these files to Git or sharing them with teammates creates instant credential leak vulnerabilities.
Masks sensitive fields as {{SECRET_PASSWORD}} and encrypts secrets in memory via native AES-256-GCM (Web Crypto API).
How Cryptographic Secrets Work Under the Hood:
type="password", autocomplete="current-password", and inputs with tokens like secret|token|api_key.crypto.getRandomValues) with client-side 256-bit symmetric keys.process.env.AUTO_MACRO_PASSWORD so tests execute headlessly in GitHub Actions with zero leaks.// Secure Playwright Export - Zero Hardcoded Passwords
const AUTO_MACRO_PASSWORD = process.env.AUTO_MACRO_PASSWORD || '';
// Step: TYPE id=password-field
await page.locator("#password-field").fill(AUTO_MACRO_PASSWORD);Troubleshooting & Real-World Edge Cases
Real-world web applications (especially modern authentication providers like Clerk, Supabase, Auth0, and NextAuth) introduce dynamic DOM states. Here is how to diagnose and resolve each scenario:
Modern auth widgets split sign-in across two screens (Screen 1: enter email → click Continue → Screen 2: enter password → click Sign In). When clicking "Continue", form libraries often emit both a button click and a form submit, recording redundant SUBMIT steps before Screen 2 appears.
In the FlowMacro IDE table, review your recorded steps. Simply click the Trash icon on any ghost SUBMIT steps between the username click and the password input. A clean multi-step flow should look like:
Occurs when an element takes longer than 6 seconds to render due to network latency, lazy chunk loading, or modal transitions.
Click the failed step in the table. In the Command Inspector, switch from the CSS path to an alternate ARIA locator or ID.
Click + Add Step in the IDE and choose wait (e.g. 1500ms) right before the slow element to give the SPA time to render.
Never discard an entire recording if you clicked something by accident. Use the ↑ Up and ↓ Down arrows on any step row to reorder actions, or select a step to adjust its command type, selector, or value directly in the Command Inspector.
Multi-Framework Code Exporters & CI/CD
Async TypeScript tests with page.locator() and environment variables.
Vanilla Node.js scripts for headless scraping and browser workflow verification.
WebDriver scripts utilizing WebDriverWait and ChromeOptions.
Interchangeable JSON schema compatible with Selenium IDE runners.
Automated CI/CD Workflow (.github/workflows/playwright.yml):
name: FlowMacro Playwright CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
env:
AUTO_MACRO_PASSWORD: ${{ secrets.AUTO_MACRO_PASSWORD }}Command & Keyboard Shortcuts Reference
Supported Selenium Commands
IDE Keyboard Shortcuts
Need Help or Found an Edge-Case Website?
Have an unusual form, shadow DOM obstacle, or feature request? We actively monitor support inquiries and provide hands-on assistance.