Project Brief — Build a Test Data Generator CLI Tool

For seven chapters you've been building toward this — variables, functions, arrays, async, the DOM. The capstone applies all of it to a single, real, useful tool: qa-datagen, a command-line test data generator your team can drop into any project. This lesson is the brief — the requirements, the architecture, the success criteria. The next lesson walks you through the implementation step by step.

The scenario

Your team has a problem every QA engineer has had: generating realistic test data is tedious. Manually crafting 50 user records — different names, emails, roles, sensible dates — eats hours. Worse, hand-crafted fixtures drift apart over time, leading to flaky tests when one suite uses alice@test.com and another uses something else.

Your job: build a CLI tool that does it for them. A teammate types:

node qa-datagen.js --type users --count 10 --output output/users.json

…and gets a JSON file with ten realistic test users — varied names, valid emails, sensible roles, recent timestamps — ready to load as a fixture. Run it again and the file refreshes. Add --type products and the same tool generates products. Add --type orders and it generates orders.

This is exactly the kind of small, focused utility every team eventually writes. By the end of this chapter you'll have a working version, and you'll have exercised every JavaScript concept this course has covered.

What the tool does

1. Reads a config file (config.json) that defines the data types it can generate (users, products, orders) and the rules for each — pools of first names, last names, domains, roles, prices, statuses. Adding a new field or expanding the name pool is a config change, not a code change.
2. Accepts command-line arguments:
   • --type <name> — what to generate. Required. (users, products, orders.)
   • --count <n> — how many items. Default 5.
   • --output <path> — output file path. Default output.json.
3. Generates realistic fake data for the chosen type — random but plausible names, valid email addresses, prices in a reasonable range, dates within the last 30 days, etc.
4. Writes the generated data to a JSON file — pretty-printed (2-space indent) so a human can open it in a diff and read it.
5. Prints a summary line — Generated 10 users → output/users.json — so the user knows it worked.

Skills you'll use

This project is a worked example of the whole course. As you build it, tick these off:

• Variables and types (chapter 1) — config values, default arguments, generated data.
• Control flow (chapter 2) — if/else for argument validation, switch for routing by --type.
• Functions and scope (chapter 3) — every step is a small named function with a single responsibility.
• Arrays and objects (chapter 4) — config pools, generated items, Array.from({ length }, ...) for bulk generation, JSON.parse and JSON.stringify for I/O.
• Async (chapter 5) — synchronous file I/O is fine for a CLI tool, but the patterns translate directly to fs/promises if you want to convert.
• DOM (chapter 6) — not used here; this is a Node.js CLI tool, not a browser tool. Worth noticing: the same JavaScript runs both places.
• Error handling (chapter 7) — try/catch around config reads, descriptive errors when arguments are wrong, structured console output.

Folder structure

A small project, one folder, predictable layout:

qa-datagen/
├── config.json             ← data generation rules
├── qa-datagen.js           ← main script (entry point)
├── generators/
│   ├── users.js            ← user data generator
│   ├── products.js         ← product data generator
│   └── orders.js           ← order data generator
└── output/                 ← generated files go here (created if missing)

Each generator is a separate file exporting one function. The main script orchestrates: parse the args, load the config, dispatch to the right generator, write the output. Keeping the generators in their own files means adding a new data type is a tiny PR — one new file, one entry in the dispatch table — not a sprawling change to a monolith.

How the tool flows end to end

Six steps. Each step is small enough to hold in your head. Each one matches a function in the next lesson. If you can read and explain that diagram, you already understand 80% of the implementation.

Success criteria

You're done when all of the following are true:

• Running node qa-datagen.js --type users --count 10 produces a file named output.json (or whatever you passed to --output) with exactly ten user objects.
• Each user has at minimum: id, firstName, lastName, email, role, createdAt.
• Running the same command twice produces different data (random, not memoised).
• Running node qa-datagen.js --type users --count 10 --output output/users.json creates the output/ folder if it doesn't already exist.
• Running with no --type argument prints a helpful error and exits — no stack trace dump.
• Running with a --type that doesn't exist in the config also fails cleanly.
• The output file is valid JSON — JSON.parse(fs.readFileSync(...)) round-trips it without throwing.

If you can read each line above and tick it, you've built a real CLI tool. If a teammate can run your script tomorrow without you on a video call, you've built a useful one.

Stretch goals (after the core works)

These extend the project once the basic version is solid. We'll cover them in lesson 3:

• --format csv — output as CSV instead of JSON. Practice with array methods (map, join).
• Data validation — ensure no two generated emails collide, prices are positive, dates are valid.
• --seed option — accept a seed value so the same input always produces the same output (reproducible test data is gold for CI).
• Coloured console output — green for success, red for errors, using ANSI escape codes.
• A products and orders generator — one new file per type, one new line in the dispatcher.

Don't try to do these first. Build the core, get it working end-to-end, then extend. The pattern of "make it work, make it right, make it fast" beats trying to ship a feature-complete tool on day one.

What you'll be doing for the next two lessons

• Lesson 2 (this chapter) — guided walkthrough. We build qa-datagen step by step. Every line of code is shown; you type it, run it, and watch each step pass before moving on. By the end of lesson 2, your tool generates users.
• Lesson 3 (this chapter) — review and stretch goals. A self-assessment checklist, reflection questions, and the stretch goals above. You leave with a finished portfolio piece and a clear next step in your learning.

🎯 Getting set up

Before lesson 2, do the prep:

1. In your js-for-qa workspace, create the qa-datagen folder.
2. Inside it, create the empty subfolders: generators/, output/.
3. Create empty files: config.json, qa-datagen.js, generators/users.js, generators/products.js, generators/orders.js.
4. Open the folder in VS Code. Open qa-datagen.js and add a single line: console.log("hello qa-datagen");. Run node qa-datagen.js and confirm the message prints.
5. Commit (or save) the empty scaffold so you have a clean checkpoint to return to if anything goes wrong.

That's it. The next lesson walks through the full implementation — parsing arguments, reading the config, generating users, writing the file, handling errors. Every step lines up with one of the six nodes in the diagram above. By the end of the lesson, your tool will be running.