� flowback

Record and replay user flows - capture browser interactions, reproduce bugs, and generate test scenarios.

✨ Features

• 🎥 Record browser interactions - Capture clicks, inputs, scrolls, and more
• ▶️ Replay events - Reproduce bugs automatically
• 🧪 Generate test code - Convert recordings to Playwright, Puppeteer, Cypress, or Selenium tests
• 🎯 Smart selectors - Generates optimal CSS selectors for reliable playback
• ⚡ Lightweight - No dependencies, works in any browser
• 📦 TypeScript support - Full type definitions included

📦 Installation

npm install @matebe12/flowback

🚀 Quick Start

Recording Events

import { EventRecorder } from "@matebe12/flowback";

// Create a recorder
const recorder = new EventRecorder({
  eventTypes: ["click", "input", "scroll"],
  excludeSelectors: [".ignore-this"],
});

// Start recording
recorder.start();

// Stop recording and get the session
const session = recorder.stop();

// Save the session
localStorage.setItem("bug-session", JSON.stringify(session));

Replaying Events

import { EventPlayer } from "@matebe12/flowback";

// Load the session
const session = JSON.parse(localStorage.getItem("bug-session")!);

// Create a player
const player = new EventPlayer({
  speed: 1.0, // 1x speed
  debug: true, // Log each event
});

// Load and play the session
player.loadSession(session);
await player.play();

Generating Test Code

import { CodeGenerator } from "@matebe12/flowback";

const generator = new CodeGenerator({
  framework: "playwright",
  language: "typescript",
});

// Generate test code
const testCode = generator.generate(session);
console.log(testCode);

📖 API Reference

EventRecorder

const recorder = new EventRecorder(options);

Options:

• eventTypes?: RecordableEventType[] - Events to record (default: all)
• excludeSelectors?: string[] - CSS selectors to exclude
• mouseMoveThrottle?: number - Throttle mouse move events (ms)
• recordScroll?: boolean - Record scroll events (default: true)
• maxDuration?: number - Max recording time in ms (0 = unlimited)

Methods:

• start() - Start recording
• pause() - Pause recording
• resume() - Resume recording
• stop() - Stop and return session
• getState() - Get current state
• getSession() - Get current session

EventPlayer

const player = new EventPlayer(options);

Options:

• speed?: number - Playback speed multiplier (default: 1.0)
• minDelay?: number - Minimum delay between events (ms)
• maxDelay?: number - Maximum delay between events (ms)
• debug?: boolean - Enable debug logging (default: false)

Methods:

• loadSession(session) - Load a recording session
• play() - Start playback
• pause() - Pause playback
• resume() - Resume playback
• stop() - Stop playback
• getState() - Get current state
• getProgress() - Get progress (0-1)

CodeGenerator

const generator = new CodeGenerator(options);

Options:

• framework?: 'playwright' | 'puppeteer' | 'cypress' | 'selenium' - Target framework
• language?: 'javascript' | 'typescript' - Output language
• selectorStrategy?: 'id' | 'class' | 'text' | 'xpath' - Selector priority

Methods:

• generate(session) - Generate test code from session

🎯 Use Cases

1. Bug Reporting

Record the steps that led to a bug and share the recording with your team.

// In your error handler
window.addEventListener("error", () => {
  const session = recorder.stop();
  sendToServer(session); // Send to bug tracking system
});

2. E2E Test Generation

Record manual testing sessions and convert them to automated tests.

// Record user actions
recorder.start();
// ... user performs actions ...
const session = recorder.stop();

// Generate Playwright test
const generator = new CodeGenerator({ framework: "playwright" });
const test = generator.generate(session);
fs.writeFileSync("test.spec.ts", test);

3. User Behavior Analysis

Understand how users interact with your application.

recorder.start();

// Record for 5 minutes
setTimeout(() => {
  const session = recorder.stop();
  analyzeUserBehavior(session);
}, 5 * 60 * 1000);

4. Demo Automation

Create automated demos of your application.

// Record the demo
const session = recordDemo();

// Replay on demand
const player = new EventPlayer({ speed: 0.8 });
player.loadSession(session);
await player.play();

🔧 Advanced Examples

Custom Event Filtering

const recorder = new EventRecorder({
  eventTypes: ["click", "input"],
  excludeSelectors: [".analytics-tracker", "[data-ignore]", ".cookie-banner"],
});

Controlled Playback

const player = new EventPlayer({ debug: true });
player.loadSession(session);

// Play first half
await player.play();
if (player.getProgress() >= 0.5) {
  player.pause();
}

// Continue after inspection
await player.resume();

Multi-Framework Export

const frameworks = ["playwright", "puppeteer", "cypress"];

frameworks.forEach((framework) => {
  const generator = new CodeGenerator({ framework });
  const code = generator.generate(session);
  fs.writeFileSync(`test.${framework}.ts`, code);
});

🌐 Browser Support

• Chrome/Edge: ✅
• Firefox: ✅
• Safari: ✅
• Opera: ✅

📝 License

MIT © leesangyeon

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🐛 Known Limitations

• iframes are not currently supported
• Shadow DOM elements may not be recorded correctly
• File uploads cannot be fully replayed
• Some complex interactions (drag & drop) may need manual adjustments

🔮 Roadmap

• [ ] iframe support
• [ ] Shadow DOM support
• [ ] Network request recording
• [ ] Screenshot capture
• [ ] Video recording
• [ ] Chrome extension
• [ ] Visual playback UI
• [ ] Cloud storage integration

📧 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ by matebe12