Testcraft Studio frontend 07: README.md

# Testcraft Studio

A React frontend for source-linked test cases. React and React DOM are the only runtime packages. Vite handles the development server and production build. Styling, icons, routing, state, Excel template parsing, and lightweight interactions are implemented locally without additional libraries.

## Run the office presentation

The office ZIP includes a prebuilt `dist` folder. With Node.js installed, open PowerShell in the project folder and run:

```powershell
node serve.cjs
```

Open http://127.0.0.1:5175/. Keep the terminal open. Stop with Ctrl+C. Use `node serve.cjs 5176` if port 5175 is already in use.

## Development

Use Node.js 20.19+ in the 20.x release line, or Node.js 22.12+.

```powershell
npm.cmd ci
npm.cmd run dev
npm.cmd test
npm.cmd run build
```

## Start a new testing journey

1. Select a team and enter the system password.
2. Create a fresh workspace with a name and purpose.
3. Create its System Baseline using any one Business, Technical, or Functional / Bug Information document.
4. Submit the baseline for Administrator approval. It remains unavailable until approved.
5. An Administrator reviews the exact document version and approves or rejects the request.
6. Open the approved workspace evidence. Add source-linked requirements and optional CR documents.
7. Open Workspace chat to ask document questions, request sources, or generate Technical, Functional, or Business test cases. Refine a draft with follow-up requests, inspect its source revisions, and save it to Test suites. Optional clarifications stay in a collapsed section without a total counter.
8. Choose the standard test format or upload an Excel `.xlsx` / CSV template. Review its first-row headers before applying it.
9. Generate test cases from the chat composer or Generate test cases page. For example, ask “Generate technical test cases” or “Generate functional test cases for CR-1042”, then “Only negative scenarios”. Open clarification questions do not block generation; expected outcomes come from available source-backed rules. Missing evidence produces an explanation instead of invented cases.
10. Review and edit the resulting test scenarios. Export CSV in the selected template's column order.
11. In Knowledge versions, select the CR revisions and apply the selection. Choose **Merge CRs into baseline**, name the proposed baseline, and submit the merge for Administrator approval.
12. The Administrator reviews the retained documents, added CR evidence, and rule changes, then selects **Approve CR merge**. This creates the next baseline version, preserves unchanged knowledge and the old baseline, and marks the CRs as incorporated.
13. To edit baseline documents, add or remove files and submit the new version for approval. The previous approved version remains available while the edit is pending.

Fresh installations contain no workspaces, baselines, documents, or test suites. Default templates are included. Existing browser records are retained when upgrading from the previous frontend.

## System access

There are two access levels: User and Administrator. MCM means Membership and Collateral Management; Membership is an alias of MCM.

Public sample system passwords for the frontend presentation:

- User: `team-demo`
- Administrator: `admin-demo`

Both use the same team-selection and system-password form. Administrators can add teams and approve baseline creation and edits. Other testing workflows are available to Users. These sample password checks are browser-local prototype behavior, not production authentication.

## Excel templates

Upload an unencrypted `.xlsx` workbook or CSV smaller than 2 MB. Put at least two unique column names in the first row of the first worksheet. The frontend reads string and cached cell values, including shared strings and inline strings; it does not execute formulas or macros. Up to 100 example rows and 200 columns are supported. Save legacy `.xls` files as `.xlsx` first.

The imported column order is retained in test exports. Unknown custom columns remain editable fields rather than invented business data. Sample template and document files are available under `tests/fixtures/`.

## Integration boundaries

- Records and conversations use browser local storage. Original uploads use IndexedDB. Files and conversations do not transfer with the project ZIP.
- The application validates file size/type and retains checksums. TXT, Markdown, and SQL have local readable previews. PDF/DOCX extraction awaits backend integration.
- Workspace chat uses a local evidence adapter for document lookup, source follow-ups, typed test-case drafts, and scoped refinements. Technical cases require Technical evidence. Responses and drafts retain cited source revisions, and changed workspace knowledge prevents saving or refining stale drafts. Saved suites are independent review copies and CSV exports retain template columns and source snapshots.
- This frontend does not call an LLM. `src/chatAssistant.js` exposes `requestWorkspaceAssistant(request, { state, signal, transport })` as the future backend boundary, with an abort signal, workspace context, conversation history, and validated structured responses. Backend retrieval, free-form reasoning, authentication, and model calls remain deferred; keep API keys on that future server.
- Test generation uses source-linked local fixtures and reviewed requirements. It does not claim comprehensive AI-generated coverage.
- Baseline versions and document approval snapshots are immutable in the frontend workflow. Backend authentication and approval enforcement are deferred.
- The static server uses Node built-ins and serves only the frontend on the local loopback interface. It is not an application backend.
- Light/dark themes, responsive navigation, keyboard focus, reduced-motion behavior, and brief CSS hover transitions are included. The optional DM Sans font falls back to system fonts offline.