> ## Documentation Index
> Fetch the complete documentation index at: https://docs.testfactors.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Organize test scenarios and categories
> Generate test scenarios from your workbook in seconds with the TestFactors AI assistant, then organize them into categories, refine, and approve.
**This is where most of the magic happens.** One click here turns a 200-row workbook into a structured, reviewed test plan in about 15 seconds.
## What this module does
A **scenario** is a thing you want to test — e.g. *"Hire a US employee into an active position"* or *"Terminate an employee with future-dated leave."* Scenarios are grouped into **categories** like *Hire*, *Termination*, *Job Change*, *Happy Path*, or *Negative / Validation*.
This module gives you two superpowers:
1. **Generate scenarios with AI** — click a button, the AI reads your workbook and proposes 20–40 scenarios organized by category. You review, approve, edit, or reject.
2. **Reuse scenarios across test cycles** — categories live at the project level. The same *"Hire"* category can appear in Cycle 1, Cycle 2, and a regression cycle — no duplication.
You get two layers of categories, automatically:
| Layer | Where it comes from | Examples |
| ------------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Baseline** (10 universal categories, instant) | Built into TestFactors — present on every project | Happy Path · Negative / Validation · Permissions · Workflow / Approval · Integration · Edge Case · Data Variants · Audit · Concurrency · Mass Operations |
| **Functional** (15–25 categories, 10–15 seconds) | AI reads your workbook and proposes them | Hire · Rehire · Termination · Promotion · Job Change · Pay Rate Change · Leave of Absence · Position Management · … |
The functional categories are unique to your workbook — they reflect what *your* HR config actually does.
***
## Who uses this module
| Role | Generate categories | Edit categories | Add scenarios | Approve / promote |
| ------------------------------ | ------------------- | --------------- | ------------- | ----------------- |
| **Project Manager+** | Yes | Yes | Yes | Yes |
| **Test Manager / Coordinator** | Yes | Yes | Yes | Yes |
| **Module Process Owner** | No | Limited | Yes | Yes |
| **Developer / Tester** | No | No | Yes | No |
| **Viewer** | No | No | No | No |
If the **+ Generate Categories** button is missing, your role doesn't include category generation. Ask your Project Manager.
***
## Before you start
You need:
* **A processed workbook** in this project. If you haven't uploaded one yet, see [Workbooks](/platform/workbooks).
* **A test cycle picked.** Categories are scoped to a cycle — same category can be reused across cycles, but generation happens for one cycle at a time. If you have only one cycle, it's auto-selected.
* **About 5 minutes** for the generation + your initial review.
***
## Step-by-step: generate scenarios with the AI
From the project's left sidebar, click **Scenarios**. You'll see categories grouped by SF module (Employee Central, Compensation, etc.).
On the left, click the SF module you want to work in (e.g. **Employee Central**). The right pane shows that module's categories. First time? It's empty — that's normal.
The empty state has a primary button: **Generate Categories**. Click it.
Within \~1 second you'll see **10 baseline categories** appear (Happy Path, Negative/Validation, etc.) — these are universal and come instantly.
Below them, a small progress banner appears:
> ⟳ AI is reading your workbook… Added 0 categories so far.
Over the next 10–15 seconds, AI-generated functional categories appear one by one — Hire, Termination, Job Change, etc. The banner counter updates live.
Each AI-generated category has a small **\[AI]** badge so you can tell them apart from baseline ones.
If you have no workbook knowledge yet (you uploaded a workbook but the parser found nothing testable), only the 10 baseline categories will appear, and you'll see a small message offering to upload a workbook or add categories manually.
For each category you have three choices:
* **Keep** (do nothing — it's already Active)
* **Edit** — rename, change description, change position
* **Demote** — hide it from this cycle without deleting (you can restore later by clicking Generate again)
If you accidentally demote categories you wanted, just click **Generate Categories** again. TestFactors restores demoted categories in a single click (no AI tokens spent — it's free).
Click any category name. You land on the **Category detail view**, which lists scenarios in that category.
For each scenario you can:
* **Generate scenarios with AI** — same pattern as categories, but for individual scenarios. The AI proposes 5–15 scenarios per category in \~10 seconds.
* **+ New scenario** — write one manually
* **Reorder** scenarios with drag-and-drop
**That's the core loop.** Once your categories and scenarios look right, the next step is generating test cases from them. See [Test Cases](/platform/test-cases).
***
## Refining AI output with chat
Every generation surface in TestFactors has a chat panel on the right where you can refine the output in plain English. After categories or scenarios have generated, try:
> *"Add more edge cases around international transfers"*
>
> *"Group the termination scenarios by reason code"*
>
> *"Skip the mass-operation scenarios for now — we'll handle those in Cycle 2"*
>
> *"The 'Hire' category is too broad — split it into 'New Hire' and 'Rehire'"*
The AI proposes changes — you approve or reject each one before they take effect.
***
## Re-running the AI after the workbook changes
If your workbook gets updated (new sheets, new fields, a corrected spec), you can re-run the AI to pick up the changes without losing your existing categories:
Click the module on the left of the Scenarios tab.
Top-right of the module pane is a small menu: **↻ Refresh from workbook ▾**. Click it and choose **Re-run AI suggestions**.
A dialog confirms what will happen:
> This will read the latest workbook knowledge and may add new functional categories on top of what's already here. Existing categories won't be removed or renamed.
Click **Re-run AI**.
Same progress banner as the initial generation. When polling stops, a toast shows how many new categories were added (often 0–5; the AI dedupes against your existing list).
***
## Reusing categories across test cycles
Categories aren't locked to one cycle — they're project-level entities you can link to as many cycles as you want.
Click the category name in any cycle.
In the category's action menu, choose **Link to cycles…**. A multi-select picker shows every cycle in the project.
Tick the cycles you want this category to appear in. The category (and any scenarios under it) become visible in those cycles too.
Each row shows a small badge: **Used in N cycles**.
To remove a category from a specific cycle (without deleting it from the project), use **Unlink from this cycle** from the same menu.
This is how you build a **regression cycle**: link every "stable" category from previous releases into it, then add only the new categories for what's changing in this release.
***
## Tips
Even if you know exactly which categories you want, generate first — the AI's proposals often surface categories you'd have missed (Concurrency, Mass Operations, Audit).
Demote what you don't need, keep what you do. You can re-generate any time. Spending 30 minutes "perfecting" the first pass is wasted effort.
Asking *"merge the two Termination categories"* in chat is much faster than doing it manually in the UI.
Link a category to a regression cycle freely. Reused scenarios are valuable too, but they often need cycle-specific tweaks — review before reuse.
When you reject an AI-proposed category, take 5 seconds to type *why*. That feedback trains the AI to do better on your next project.
A cycle with 60 categories is usually too broad. Aim for 10–25 categories per cycle, each with 5–15 scenarios. Bigger than that = split into more cycles.
***
## Troubleshooting
Most likely your role doesn't include `scenario_categories:write`. Roles that *do*: Project Manager, Client Manager, Org Admin, Test Manager. Ask your Project Manager to update your role or to generate on your behalf.
This usually means TestFactors couldn't find functional context for this module in your workbook. Three things to check:
1. **Did your workbook actually upload successfully?** Open the Workbooks tab — the workbook should say "Ready" with a sheet count.
2. **Did the module get scanned?** In the workbook detail, the **Knowledge** tab should show extracted facts for this SF module.
3. **Is the module right?** If you tagged the workbook as "Compensation" but you're generating in "Employee Central," the AI has no source material. Check the workbook's **SF Module** tag.
Fix any of those, then click Generate again.
This is normal — TestFactors won't burn AI tokens re-running on a cycle+module that already has AI categories. Use **↻ Refresh from workbook → Re-run AI suggestions** instead to explicitly re-run.
Typical generation takes 10–15 seconds, never more than 60. If it's longer:
1. **Refresh the page** — sometimes the progress banner is stale. Categories will be there.
2. **Try once more.** Click **Refresh from workbook → Re-run AI suggestions**.
3. **If it keeps stalling**, contact your Admin with the project name and timestamp.
Click **Generate Categories** again. TestFactors restores any demoted categories in this cycle+module in a single click — and shows a toast *"Reactivated N categories that were previously demoted."* No AI tokens are spent on the restore.
Open the category, click the **⋮** menu, choose **Delete**. Deletion is permanent and removes all scenarios under it. Use Demote instead if you might want it back.
Two things help:
1. **Demote (don't delete)** the unwanted category. Demoted rows are passed to the AI as "don't propose this name."
2. **Use the rejection feedback box** to say *why* — the AI uses this signal on the next run.
***
## Related guides
Upload and review your workbook — categories generate from it.
Next step: turn approved scenarios into specific test cases.
Add domain knowledge so the AI generates better categories next time.
Ask plain-English questions about why a category was proposed.