# Test Card Generator — Product Requirements (v2.0)

Cardgen is a test-data tool for developers and testers. It generates batches of fake payment card numbers for a chosen network (Vela, Orbit, Atlas Express, Summit Club, Comet, Lotus, Tidal or a random mix), validates any number with the Luhn checksum and network rules, and keeps a per-tab history of batches. The numbers are never real and nothing is charged.

**Problem.** Testers need dependable fake card data: exactly the number of cards requested, in the right length and format for each network, passing the checksum, and reproducible when they need the same data again.

## Users
- **QA engineer** — Generate a known number of valid cards per network to fill a checkout test.
- **Developer** — Validate a number and call the same rules from a script, with a seed for repeatable data.

## Goals
- A batch contains exactly the number of cards requested, from 1 to 50.
- Every generated number has the length, prefix and CVV size of its network and passes the Luhn checksum.
- The validator tells a valid number from an invalid one and says why.

## Generating a batch (GEN)

Choosing a type and count and reading the result.

- **FR-GEN-01** (Must) Choosing a card type and a count and clicking Generate shows a batch with exactly that many cards, whose heading names the count and the type.
  - The Generate tab opens with Card Type "Select card type"; while working the button reads "Generating…"
  - 10 Vela: "Generated 10 Vela cards", exactly 10 cards (the result panel scrolls), each starting with 4 and having 16 digits in groups of 4
  - 1 card: "Generated 1 Vela card" (singular)
- **FR-GEN-02** (Must) The maximum count of 50 returns exactly 50 cards and every smaller count returns exactly that many.
  - 50 Orbit: "Generated 50 Orbit cards"; in CSV output 50 data rows under the header
  - 50 Vela: the heading says 50 and the panel holds 50 cards
- **FR-GEN-03** (Should) A seed makes a batch reproducible: the same seed, type and count always give the same numbers in the same order; another seed gives different numbers.
  - Opening with ?seed=42 shows Seed 42 in Advanced options; the caption reads "seed 42"
  - Generating again gives a new batch id and the same three numbers; seed 43 gives different numbers

## Count and type validation (CNT)

Messages for invalid input; nothing is generated on error.

- **FR-CNT-01** (Must) The count must be a whole number from 1 to 50; every invalid count shows its own message under Number of Cards and no result panel appears.
  - Empty: "Enter how many cards to generate (1–50)"
  - 0 or -1: "Generate at least 1 card"
  - 2.5: "Number of cards must be a whole number"
  - 51: "You can generate at most 50 cards at a time"
  - A valid count afterwards clears the message
- **FR-CNT-02** (Should) A card type is required.
  - Generating without a type shows "Choose a card type" under Card Type and outlines the listbox button in red

## Network formats (NET)

Length, prefix and CVV size per network.

- **FR-NET-01** (Must) Atlas Express numbers have 15 digits grouped 4-6-5, start with 34 or 37 and carry a 4-digit CVV.
  - Every one of 5 cards matches; a 16-digit Atlas number is wrong
- **FR-NET-02** (Should) Summit Club numbers have 14 digits grouped 4-6-4, start with 36 or 38 and carry a 3-digit CVV.
  - Every one of 4 cards matches
- **FR-NET-03** (Could) "Random (mixed)" draws from several networks, each in its own format.
  - 20 cards show at least 3 network names
  - Atlas numbers have 15 digits, Summit Club 14, the others 16

## Card Type listbox (TYP)

Keyboard operation of the custom control.

- **FR-TYP-01** (Could) The Card Type control works as a listbox from the keyboard and by mouse.
  - ArrowDown on the button opens the list with "Random (mixed)" highlighted
  - End highlights "Tidal"; Enter closes the list, shows "Tidal" and returns focus to the button
  - Escape closes the list and keeps the current choice
  - Choosing an option by mouse closes the list and shows the name

## Validator (VAL)

Luhn checksum and network rules.

- **FR-VAL-01** (Must) Every generated number passes the validator, which names the network and the checksum result.
  - A Comet number pasted into Validate: "✓ Valid number"; Network Comet; Luhn checksum Pass
  - Copy on a card briefly shows "Copied"
- **FR-VAL-02** (Must) The validator rejects a number whose checksum fails, whose length does not fit its network or whose prefix is unknown, and says why.
  - 4111 1111 1111 1111: "✓ Valid number"; Network Vela; Digits 16; Luhn Pass
  - 3782 822463 10005: "✓ Valid number"; Network Atlas Express; Digits 15
  - 4111 1111 1111 1112: "✗ Invalid number"; Luhn checksum Fail; reason "The Luhn checksum fails"
  - 4111 1111 1111 111: reason "Vela numbers have 16 digits, this one has 15"
  - 9999 0000 1111 2222: Network Unknown; reason "The prefix does not match a known network"
  - The service: 5555 5555 5555 4444 gives {network:"Orbit", valid:true}
- **FR-VAL-03** (Should) Spaces and dashes in the input are ignored; any other character is rejected.
  - Empty: "Enter a card number"
  - 4111-1111-1111-1111 is valid and shown as 4111 1111 1111 1111
  - 4111 1111 1111 111a: "Card numbers contain digits only (spaces and dashes are ignored)"

## Options and export (OPT)

Include toggles, formats and bulk actions.

- **FR-OPT-01** (Should) The Include options hide CVV, expiry and cardholder name from the cards and from JSON and CSV output.
  - With CVV and Cardholder name unticked the cards show only "Valid thru"
  - JSON objects hold network, number and expiry; numbers have no spaces
  - CSV header is "network,number,expiry"
- **FR-OPT-02** (Could) "Copy all" and "Download CSV" export the whole batch.
  - "Copied 4 cards" appears briefly
  - The file cards-B-<n>.csv has a header and 4 rows

## History (HIS)

Per-tab list of batches.

- **FR-HIS-01** (Could) History lists the newest batch first and can reopen a batch.
  - A fresh tab lists B-2 (Orbit, 3 cards, seed 2024) above B-1 (Vela, 5 cards, seed 7)
  - Open on B-1 shows "Generated 5 Vela cards" and the caption "Batch B-1 · seed 7"
  - A new batch of 2 Random (mixed) cards appears first as B-3
- **FR-HIS-02** (Could) Clear history asks for confirmation and, once confirmed, stays cleared after a reload.
  - "Delete all batches?" with Delete and Keep; Keep leaves both batches
  - Delete shows "No batches yet." and it is still shown after a reload

## Generate and validate service (API)

The same rules for scripts.

- **FR-API-01** (Could) The generate service enforces the same rules as the page and returns structured errors.
  - type vela, count 10, seed 42: 200 with 10 cards and seed 42
  - count 51: 422 {field:"count", message:"You can generate at most 50 cards at a time"}
  - type bogus: 422 "Unknown card type \"bogus\""

## Glossary and rules

- **Luhn checksum** — The check-digit rule every real card number must satisfy.
- **Seed** — A number that makes random generation repeatable.
- **Batch** — One click of Generate; it gets an id such as B-3.

## Out of scope

- Real payment processing
- Clipboard contents (browsers may block clipboard access)