npm package: @matebe12/flowback
Description: Record and replay user flows - capture browser interactions, reproduce bugs, and generate test scenarios
Author: matebe12
Latest version: 0.1.0

# � 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

```bash
npm install @matebe12/flowback
```

## 🚀 Quick Start

### Recording Events

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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.

```typescript
// 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.

```typescript
// 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.

```typescript
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.

```typescript
// 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

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

### Controlled Playback

```typescript
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

```typescript
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](https://github.com/matebe12/flowback)
- 🐛 [Issue Tracker](https://github.com/matebe12/flowback/issues)
- 💬 [Discussions](https://github.com/matebe12/flowback/discussions)

---

Made with ❤️ by matebe12