🧪 FlowT – Flow-Based Automation Testing Tool

FlowT is a flow-first automation testing CLI built on top of Playwright.

It is designed to help teams record real user journeys, reuse authentication safely, and run deterministic test sets in CI/CD — without introducing hidden state, magic configs, or brittle abstractions.

Record once. Run anywhere. Deploy with confidence.

---

✨ Why FlowT?

Most automation frameworks focus on test cases. FlowT focuses on flows — real user journeys that matter in production.

FlowT gives you:

• ✅ Flow-based testing (one journey = one file)
• ✅ Domain-first organization (multi-env friendly)
• ✅ Secure auth reuse (CI-safe)
• ✅ Deterministic CI runs
• ✅ Interactive dev experience
• ✅ Zero vendor lock-in (pure Playwright)

---

🧠 Core Concepts

1️⃣ Flow

A flow is a complete user journey:

• login
• checkout
• payout
• admin action

Each flow:

• lives in a single .flow.spec.ts file
• is recorded using Playwright Codegen
• is easy to review, debug, and maintain

---

2️⃣ Domain-Based Structure

Flows and auth are grouped by domain, not by feature.

tests/
  example.com/
    login.flow.spec.ts
    checkout.flow.spec.ts

This makes it trivial to:

• test multiple environments
• clone flows between domains
• reason about environment-specific behavior

---

3️⃣ Explicit Authentication

Authentication is:

• recorded manually
• stored as Playwright storageState
• never auto-encrypted
• never auto-committed

You control:

• when to encrypt
• when to decrypt
• where auth is used

This makes FlowT safe for CI/CD by design.

---

📦 Installation

npm install -g flowt

Or via repository:

npm install
npm link

---

🚀 Quick Start

flowt init
flowt auth record admin-login https://example.com/login
flowt record checkout https://example.com --auth admin-login
flowt run-flow checkout --headed

---

🛠 Project Initialization

flowt init

Creates:

.
├── playwright.config.ts
├── tests/
├── auth/          # gitignored
├── .env           # FLOWT_KEY generated
├── .gitignore

Notes

• auth/ is runtime-only
• .env contains FLOWT_KEY used for encryption/decryption
• Playwright is installed automatically if missing

---

🔐 Authentication

Record Authentication

flowt auth record admin-login https://example.com/login

Creates:

auth/
  example.com/
    admin-login/
      auth.js
      state.json
      meta.json

---

List Auth

flowt auth --list
# or
flowt list auth

---

Encrypt Auth (for CI)

flowt auth enc

• Interactive selection
• Encrypted output stored in auth_enc/auth_enc.json
• Safe to commit

Optional:

flowt auth enc admin-login --remove

---

Decrypt Auth (CI / Runtime)

FLOWT_KEY=your_key flowt auth dec

Restores decrypted auth into auth/ for execution.

---

Refresh Authentication

flowt auth refresh example.com/admin-login

Re-runs the original login flow and updates the state.

---

📝 Recording Flows

flowt record checkout https://example.com --auth admin-login

Creates:

tests/example.com/
  checkout.flow.spec.ts
  checkout.flow.meta.json

Flow files:

• recorded using Playwright Codegen
• auto-prefixed with FLOW:
• ready to clean and stabilize

---

📃 Listing Flows

flowt flows --list
# or
flowt list flows

Filters:

flowt flows --critical
flowt flows --tags smoke,checkout

---

▶️ Run a Single Flow

flowt run-flow checkout

Options:

flowt run-flow checkout --headed
flowt run-flow checkout --project chromium
flowt run-flow checkout --auth admin-login

FlowT automatically finds the flow across all domains.

---

🧠 Runs: Dev vs Deploy (Important)

FlowT separates interactive development from deterministic deployment.

---

🧪 Dev Run (Interactive)

flowt run dev test

What happens:

• Interactive flow selection (tree UI)
• Selected flows are executed
• Metadata saved to runs/test.json

Used for:

• local testing
• defining CI test sets

---

🚀 Deploy Run (CI / Production)

flowt run deploy test

What happens:

• Reads runs/test.json
• Executes the exact same flows
• No interaction
• No mutation

Used for:

• CI pipelines
• release gates
• production validation

---

📂 Runs Folder

runs/
  test.json

Example:

{
  "runName": "test",
  "flows": [{ "domain": "example.com", "file": "checkout.flow.spec.ts" }]
}

---

🔁 Clone Between Domains

flowt clone staging.example.com prod.example.com

What it does:

• copies flows
• copies auth (if present)
• rewrites all URLs
• preserves structure

Perfect for:

• staging → prod
• qa → uat

---

📊 Dashboard

Generate dashboard:

flowt dashboard

Serve locally:

flowt dashboard --serve

Features:

• all test runs
• pass/fail stats
• duration
• clickable Playwright reports
• live reload

---

📃 Centralized List Commands

flowt list auth
flowt list flows
flowt list runs

No logic — only visibility.

---

🚦 CI / CD Usage

FlowT is CI-first by design.

CI Principles

• no recording in CI
• no interaction
• no plaintext auth committed
• deterministic execution

---

Required Secret

FLOWT_KEY=<same key used during auth enc>

---

GitHub Actions Example

name: FlowT CI

on:
  push:
    branches: [main, develop]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-node@v3
        with:
          node-version: "18"

      - run: npm install
      - run: npx playwright install --with-deps
      - run: npm run build
      - run: npm link

      - name: Decrypt auth
        env:
          FLOWT_KEY: ${{ secrets.FLOWT_KEY }}
        run: flowt auth dec

      - name: Run tests
        run: flowt run deploy test

      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: flowt-test-reports
          path: flowt_test/reports

---

📦 What to Commit

✅ Commit:

• tests/**
• runs/*.json
• auth_enc/**
• playwright.config.ts

❌ Never commit:

• auth/**
• decrypted state
• credentials

---

🧱 Folder Structure

flowt_test/
├── tests/
├── auth/        # gitignored
├── auth_enc/
├── runs/
├── reports/
├── playwright.config.ts
├── .env

---

🎯 Design Guarantees

• deterministic CI runs
• explicit auth lifecycle
• no hidden state
• no magic
• pure Playwright underneath

---

🧠 Philosophy

“Record flows like users behave. Run locally with freedom. Deploy with certainty.”

---

🔗 Links

• GitHub: https://github.com/paneruvipin/flowt
• Playwright: https://playwright.dev