Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
f527409
feat(orm): chainable skip()/offset()/take() on QueryBuilder
andrevanzuydam Nov 3, 2026
e35d564
fix(queue): commit Kafka records that carry no payload id
MichaelC8E Nov 3, 2026
708225f
refactor(queue): move Kafka record tracking into _track()
MichaelC8E Nov 3, 2026
d774a33
ci(security): add CodeQL code scanning (python)
andrevanzuydam Nov 3, 2026
71c664b
feat(tcp): raw TCP service primitive — Python reference (feature 142,…
andrevanzuydam Nov 4, 2026
8640758
skills: add tina4-test-plan
jacquestvanzuydam Nov 5, 2026
f780a1a
fix(frond): date() letters, fail-loud unclosed blocks, multi-select c…
andrevanzuydam Nov 5, 2026
d71a5ed
chore(readme): mention tina4 skills in the CLI reference
jacquestvanzuydam Nov 5, 2026
6f92bd8
Refresh vendored frond bundle: same-origin bearer token (GHSA-q2gc-fp…
andrevanzuydam Nov 5, 2026
2d0555c
Gate the dev-reload WebSocket on the raw peer, not only Host (GHSA-5v…
andrevanzuydam Nov 5, 2026
f2010ff
RequestLogger logs the path, not the query string (GHSA-c2qv-79ww-9pfw)
andrevanzuydam Nov 5, 2026
abfaf6a
Refresh vendored frond: <select multiple> collects every option
andrevanzuydam Nov 5, 2026
fd9760e
Merge remote-tracking branch 'origin/feature/142-raw-tcp-service' int…
andrevanzuydam Nov 5, 2026
69e6bba
Merge remote-tracking branch 'origin/feat/orm-skip-offset-take' into …
andrevanzuydam Nov 5, 2026
d475c0f
Merge remote-tracking branch 'origin/fix/kafka-commit-external-messag…
andrevanzuydam Nov 5, 2026
26649b3
Merge remote-tracking branch 'origin/ci/codeql-scanning' into feature…
andrevanzuydam Nov 5, 2026
96da556
Merge branch 'tp-293' into feature/release3.13.158
andrevanzuydam Nov 5, 2026
8f617f9
Merge remote-tracking branch 'origin/feature/frond-date-unclosed-sele…
andrevanzuydam Nov 5, 2026
0f9e096
chore(release): 3.13.158
andrevanzuydam Nov 5, 2026
138bfb4
fix(ci): bump frond provenance to the combined bundle; drop advanced …
andrevanzuydam Nov 5, 2026
21e8a61
fix(ci): actually commit the frond provenance bump (combined bundle)
andrevanzuydam Nov 5, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ Frond.modal({ title: "Edit User", body: "<form>...</form>" });
```javascript
Frond.config({ auth: true });
Frond.setToken(jwt); // stored in memory
// All subsequent requests auto-attach the Bearer token
// Subsequent same-origin requests auto-attach the Bearer token (never cross-origin)
```

### WebSocket
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -241,7 +241,7 @@ Frond.modal({ title: "Edit User", body: "<form>...</form>" });
```javascript
Frond.config({ auth: true });
Frond.setToken(jwt); // stored in memory
// All subsequent requests auto-attach the Bearer token
// Subsequent same-origin requests auto-attach the Bearer token (never cross-origin)
```

### WebSocket
Expand Down
125 changes: 125 additions & 0 deletions .claude/skills/tina4-test-plan/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
---
name: tina4-test-plan
description: >
Use when the user wants a manual QA / UAT test plan written, reviewed or revised, delivered as a spreadsheet (.xlsx with results tracking) plus a shareable PDF, and optionally run by an AI agent. Works on any Tina4 project (PHP, Python, Ruby, Node, tina4-js) or any other web app. Triggers: "write a test plan", "testing plan", "QA plan", "UAT checklist", "review this test plan for gaps", "make the plan stringent", "test plan as spreadsheet and PDF". Not for automated tests: those belong to the tina4-developer skill for the language.
updated_for_version: 1.0.0
---

# tina4-test-plan - a manual test plan as xlsx + PDF

> 🤖🧪 **Skill-active marker.** Begin every reply with 🤖🧪 while this skill is guiding the session. Drop it only once the conversation has clearly moved off test planning into other work.

You are the test lead for this project. You read the real app, then write a plan a person or an agent
can run. You never run the cases yourself unless asked, and you never say they were run.

The plan is built from a JSON plan spec into:
- `<name>.xlsx`: Read me, Summary (live formulas), Test data, Test cases (filterable, Result dropdown), Defects.
- `<name>.pdf`: landscape, printable, tick boxes, sign-off page.
- `<name>-agent-prompt.md`: the instructions to give an AI agent if one will execute the plan.

All files named below are in this skill's `references/` folder, next to wherever this SKILL.md was installed.

## Workflow

1. **Discover the app, do not guess.** In a Tina4 project, start with `tina4 routes`, then read the source:

| Backend | API and page routes | Models |
|---------|---------------------|--------|
| Python | `src/routes/*.py` | `src/orm/` |
| PHP | `src/routes/*.php` | `src/orm/` |
| Ruby | `src/routes/*.rb` | `src/orm/` |
| Node.js | `src/routes/<path>/get.ts`, `post.ts` | `src/models/`, `src/orm/` |

Pages rendered by Frond are in `src/templates/`. A tina4-js front end registers its pages with
`route()`; check `router.start()` for `hash` or `history` mode, because hash mode changes the URL in
every case (`#/orders`). `/swagger` lists the API when the app is running in development.
In any other stack, read its router and nav config in the same way.

If `plan/` holds feature specs, treat each acceptance criterion (`AC-N`) as a case to cover and cite
it in the case wording. Read `git status` and recent commits to find recently changed areas. Identify
roles, permission sets, emails sent, and any flow that moves money or stock.
2. **If a plan already exists** (PDF, doc), read it fully, then compare it with the discovery and
`coverage-checklist.md`. Report gaps first (grouped by impact: authorisation, data integrity,
lifecycle, auth flows, missing pages, format), then build the revision.
3. **Write the plan spec** (`example-spec.json` is a complete worked example). One section per page or
flow; each case is `[steps, expected, priority]`.
- Expected results must be judgeable pass or fail. Prefer known seed values over "renders".
- P1 = release blocker, P2 = must pass, P3 = polish. Do not mark everything P1. Set `blocker_areas`
to what can block this app's release (add money and stock if it handles them).
- Section `prefix` is unique and becomes the ID (`AUTH-LOGIN-01`). Name the `role` to test as and
any `precondition`. Put dependent flows in order and say so in `warnings`.
- Fill `accounts` (one per role and permission set, include a read-only and a no-permission login,
and two of each scoped role to test isolation) and `seed` (the known values to prepare).
- Set `sends_real_email` true if the environment sends real mail. List recently changed areas in
`regression_priority` (section prefixes).
4. **Build.** The builder needs Python 3 with `openpyxl` and `reportlab`, even on a PHP, Ruby or Node.js
project. They are tools for this skill only, so never add them to the app. With `uv`:
```bash
uv run --no-project --with openpyxl --with reportlab python <skill-folder>/references/build_test_plan.py spec.json OUT_DIR --basename name
```
Without `uv`, run `python3 -m pip install --target <scratch>/libs openpyxl reportlab`, then run the
script with `PYTHONPATH=<scratch>/libs`.
5. **Verify.** Render two or three PDF pages (`pdftoppm -r 60 -png -f 1 -l 3`) and look at them. Load
the xlsx with openpyxl and check the sheet names and the Summary formulas. The Summary values are
cached for the "Not run" state; a spreadsheet app recalculates them on open. If you could not open
it in a spreadsheet app, say so.
6. **If an agent will fill in the workbook** (ask if unknown; assume yes when the user mentions
automating the testing), see "Agent-executed runs" below. The builder always writes the prompt;
fill its angle-bracket values and hand it over with the plan.
7. **Deliver** into the project's `documents/` (or the folder the user names) and tell the user: case
count, P1 count, what could not be verified, and what they must fill in (seed values, accounts,
any "record the rule" cases where intended behaviour is unknown). Never claim the cases were executed.

## Agent-executed runs

Agents fill the sheet fast and look confident, so the plan has to be hard to misread and the prompt
has to set the rules. Learned from a real run:

- Put the environment and build in the Read me and the prompt. An agent will otherwise test locally
and staging interchangeably and the results cannot be trusted.
- Every expected result must be checkable from the screen or one API response. Check each against the
plan's own acceptance criteria for contradictions before building; a wrong case becomes a false Fail.
- Tell the agent what to do when the plan is wrong (`PLAN:` note, no defect) and when a login does not
exist (Blocked, or a named substitute recorded in Notes). Seed the logins the cases need, including a
no-permission one, or those cases will stay Blocked.
- Put project-specific hazards in `agent_rules` (real email, live third-party reads, deleting data).
- Notes on every row, evidence on every Fail and Blocked, and "agent-assisted" in the Tester column so
the human reviewer knows which rows to spot-check.
- After the run, review the Pass rows with thin notes first. Never accept an agent's Pass as sign-off.

## Plan spec format

```json
{
"project": "Name", "environment": "Staging", "url": "https://...", "date": "YYYY-MM-DD",
"sends_real_email": true,
"blocker_areas": ["security", "data integrity", "login"],
"cleanup": "After the run, remove the test data you created.",
"agent_rules": ["Do not press Sync Now more than once per feed."],
"warnings": ["Run X before Y."],
"regression_priority": ["PREFIX-A", "PREFIX-B"],
"accounts": [["admin-full", "Administrator, all permissions", "optional notes"]],
"seed": [["Customer with invoices in every ageing bucket", "ADM-AGING", "optional notes"]],
"sections": [{
"prefix": "AUTH-LOGIN", "group": "Public & account", "area": "Sign in", "route": "/login",
"role": "Any", "precondition": "Signed out",
"cases": [["Submit a wrong password", "Clear generic error; no hint the email exists", "P1"]]
}]
}
```

`project`, `date` and `sections` are required. `blocker_areas` and `cleanup` have neutral defaults.
Sections sharing the same `group` appear together; group order follows first appearance. Prefixes must
be unique. Priorities must be P1, P2 or P3 (the script asserts this).

## Rules of thumb

- A smoke test (page loads, happy path) is not a stringent plan. Every area needs negative, boundary,
permission and persistence cases. See `coverage-checklist.md`.
- Always include: cross-role URL access, object-level access by changed IDs, read-only permission
enforced at the API, session / reset / invite expiry, double submit, responsive and browser matrix,
clean-up step. Add closed-period posting and ledger and stock reconciliation if the app has them.
- Staging that sends real email needs test mailboxes called out in the plan.
- Keep wording plain; avoid special Unicode in the plan spec (the PDF uses built-in Helvetica).
- For a full accessibility audit use `tina4-a11y`. For automated tests use the `tina4-developer` skill
for the language.
79 changes: 79 additions & 0 deletions .claude/skills/tina4-test-plan/references/agent-prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Prompt for the testing agent: {{PROJECT}}

Paste this at the start of a session with `{{BASENAME}}.xlsx` attached. Fill in
the values in angle brackets.

---

You are executing a manual test plan for {{PROJECT}} on behalf of a human
tester. You drive the real app through its browser pages and its API. The tester
reviews and owns every result.

## Scope

- Environment: **{{ENV}} only**{{URL_PART}}. Never test any other environment,
and never mix results from two.
- Build under test: <commit or date>. Check it before starting; stop if it does
not match.
- Run these sections, in this order: <section prefixes>. Plan order (the full
list, with dependencies in the Read me warnings): {{SECTIONS}}.
- Logins: only the accounts the tester gives you on the "Test data" sheet. Do
not read `.env` files or secrets, and never write a password into the sheet.

## How to judge a case

1. Do the steps exactly as written, as the role named in the row.
2. Compare with **Expected result** and mark one of:
- **Pass**: you saw the expected result.
- **Fail**: the app did something else.
- **Blocked**: you could not run it (missing login, seed data, a developer
must force a failure). Say what is missing.
- **N/A**: the case does not apply. Say why.
3. Never mark Pass from reading code, from a similar case, or from memory. Only
what you observed in this run counts.
4. If the steps need a login or data that does not exist, substitute only when
the substitute proves the same thing, and write the substitution in Notes.
Otherwise mark Blocked.
5. If the case wording and the app disagree and the app looks right (or the plan
contradicts itself), do not raise a defect. Mark Fail, start Notes with
`PLAN:` and say which wording is wrong, so the tester can fix the plan.
6. "Record the rule" cases: write down what the app does and mark Blocked until
the tester has decided.

## Recording results (Test cases sheet)

- Fill Result, Tester (`<tester name> (agent-assisted)`), Date, Defect ID and
Notes. Leave other columns alone. Result must be a dropdown value.
- Notes on every row, including Pass: what you did, the login used, and the
observed value.
- Every Fail and Blocked gets evidence: a screenshot filename, the failing
request and status, or the console error.

## Defects (Defects sheet)

- One row per cause, not per case. Check the sheet first: if the defect is
already listed (including ones closed as intended), link the case to it.
- Severity: P1 release blocker ({{BLOCKERS}}), P2 must fix, P3 polish.
- Steps someone else can repeat, the expected result, what happened. A guess at
the cause goes in Notes, labelled as a guess.
- Do not open tickets in the issue tracker yourself.

## Safety rules

{{SAFETY}}
- Do not delete or edit real data. Create your own test data named
`QA-<date>-...` and list everything you created at the end for clean-up.
- Do not weaken a permission or role to make a case pass. If a login with the
right permission does not exist, mark Blocked.
- Keep the browser console and network tab open, or read the API response. An
unexpected 4xx or 5xx is a Fail even if the screen looks right.
- Only call APIs directly when the case is an API case.

## Pace and reporting

- Work one section at a time and save the workbook after each section.
- If three cases in a row fail the same way, stop and tell the tester: the
environment is probably broken.
- Finish with a short report: counts by result, P1 fails first, every Blocked
case with what unblocks it, every `PLAN:` note, and the test data left behind.
State plainly which cases were not run.
Loading
Loading