Frappe Faker — Generate Test Data from the CLI

Use this skill when you need realistic, linked Frappe/ERPNext test records for a specific DocType. Faker resolves the full dependency graph, generates all linked records via LLM, and inserts them in FK-safe order. Every run produces a Faker Batch ID that you can use to delete all generated records when testing is done.

Prerequisites

• The Frappe Faker app must be installed on the site
• Faker Settings must have a configured AI provider (check /app/faker-settings)
• The RQ background worker is not needed — CLI runs synchronously in the terminal

Workflow

1. Inspect dependencies first

bench --site <site> faker plan --doctype "<DocType>"

This shows the full dependency tree without generating anything. Look for:

• [Has data — will skip] — existing records will be reused; no generation needed
• [Cyclic] — cycle detected; generation will still proceed
• [Target] — the DocType you requested

Example output:

Dependency plan for: Salary Slip

Salary Slip  [Target]
  Salary Structure Assignment
    Employee
      Department  [Has data — will skip]
    Company  [Has data — will skip]
  Salary Structure

2. Generate records

bench --site <site> faker generate \
  --doctype "<DocType>" \
  --count <N> \
  --instructions "<free-text requirements>"

Options:

• --count / -n — number of target doctype records (dependencies get min(count, 5))
• --skip — comma-separated list of DocTypes to skip (e.g. --skip "Employee,Company")
• --instructions — natural language constraints passed to the LLM
• --no-fast-insert — use standard doc.insert() path (runs Python hooks; slower)

Example:

bench --site demo.localhost faker generate \
  --doctype "Salary Slip" --count 3 \
  --instructions "Employees are software engineers in Bangalore, monthly salary 80k-120k INR, use existing company"

Output:

Generating 3 record(s) for Salary Slip...

Batch: abc123def456  |  Created: 12  |  Failed: 0
  Department: 0 created  (skipped — has data)
  Employee: 3 created
  Salary Structure: 3 created
  Salary Structure Assignment: 3 created
  Salary Slip: 3 created

3. Run your tests

Use the generated records for whatever testing or API calls you need.

4. Clean up

bench --site <site> faker cleanup --batch <batch_id>

This deletes all records from the batch in reverse dependency order (FK-safe). Use the batch ID printed by faker generate.

bench --site demo.localhost faker cleanup --batch abc123def456
# → Deleted 12 record(s). Status: Rolled Back

Tips

• Use --instructions liberally — the LLM respects free-text constraints like dates, locations, salary ranges, roles, and relationships between records
• Skip doctypes with existing data — if your site already has Employees, use --skip "Employee" to reuse them and avoid duplication
• Check for errors — if Failed > 0, re-run with a lower count or simpler instructions; per-record errors are logged in the output
• Batch rollback is partial-crash-safe — if generation crashes mid-way, the batch still tracks all successfully inserted records; cleanup will roll back only what was tracked

Rollback from the UI

Open the Frappe Faker web app at /faker, go to History, click a run row, and use the Rollback button in the detail dialog to delete that batch's records without touching the terminal.