From 6f01665452d372527c0ae32adf697fd196fadca6 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 1 Oct 2026 09:32:56 +0000 Subject: [PATCH] usertest: sample data for sessions without a provider account (#196) Money: synthetic Acme Studio bank statements (MT940 Aug, overlapping MT940 Sep, camt.053 Aug) generated in integrations/money/fixtures/usertest/, served from the catalog host's samples/money/ and linked on the session page; money.md uses them first. Calendar, GitHub issues, Clockify and Notion: catalog.mjs builds a " (sample data)" entry per app, the same built app with store.proxy answered in the frame by the mock proxy's provider fixture, already connected, with writes persisted under the App and replayed on remount. New -sample session plans say the data is invented so the analysis does not log it as a finding. Checks: money vitest for the statements, node --test for the sample accounts, usertest/e2e/samples.mjs against the pinned atomic-server, and run.mjs for the page's sample-file links. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Qt6FnBHXdJWx9GEKuAqVBo --- docs/agents/usertest-droplet.md | 7 +- .../usertest/acme-studio-2026-08.camt053.xml | 533 ++++++++++++++++++ .../usertest/acme-studio-2026-08.mt940 | 104 ++++ .../usertest/acme-studio-2026-09.mt940 | 85 +++ .../money/fixtures/usertest/generate.mjs | 494 ++++++++++++++++ integrations/money/usertest-samples.test.ts | 73 +++ usertest/Caddyfile | 6 +- usertest/README.md | 34 +- usertest/catalog.mjs | 158 +++++- usertest/deploy.sh | 7 +- usertest/e2e/run.mjs | 33 ++ usertest/e2e/samples.mjs | 227 ++++++++ usertest/moderator/server.mjs | 17 +- usertest/moderator/sessions/README.md | 29 +- .../moderator/sessions/calendar-sample.md | 35 ++ .../sessions/issue-tracker-sample.md | 39 ++ usertest/moderator/sessions/money.md | 27 +- usertest/moderator/sessions/notion-sample.md | 37 ++ .../moderator/sessions/timesheets-sample.md | 37 ++ usertest/page/app.js | 26 + usertest/page/i18n.js | 10 + usertest/page/index.html | 8 + usertest/sample-data/README.md | 58 ++ usertest/sample-data/calendar.mjs | 173 ++++++ usertest/sample-data/issue-tracker.mjs | 25 + usertest/sample-data/notion.mjs | 17 + usertest/sample-data/proxy.mjs | 281 +++++++++ usertest/sample-data/samples.test.mjs | 258 +++++++++ usertest/sample-data/timesheets.mjs | 82 +++ 29 files changed, 2887 insertions(+), 33 deletions(-) create mode 100644 integrations/money/fixtures/usertest/acme-studio-2026-08.camt053.xml create mode 100644 integrations/money/fixtures/usertest/acme-studio-2026-08.mt940 create mode 100644 integrations/money/fixtures/usertest/acme-studio-2026-09.mt940 create mode 100644 integrations/money/fixtures/usertest/generate.mjs create mode 100644 integrations/money/usertest-samples.test.ts create mode 100644 usertest/e2e/samples.mjs create mode 100644 usertest/moderator/sessions/calendar-sample.md create mode 100644 usertest/moderator/sessions/issue-tracker-sample.md create mode 100644 usertest/moderator/sessions/notion-sample.md create mode 100644 usertest/moderator/sessions/timesheets-sample.md create mode 100644 usertest/sample-data/README.md create mode 100644 usertest/sample-data/calendar.mjs create mode 100644 usertest/sample-data/issue-tracker.mjs create mode 100644 usertest/sample-data/notion.mjs create mode 100644 usertest/sample-data/proxy.mjs create mode 100644 usertest/sample-data/samples.test.mjs create mode 100644 usertest/sample-data/timesheets.mjs diff --git a/docs/agents/usertest-droplet.md b/docs/agents/usertest-droplet.md index 4e484602c..05b190fe3 100644 --- a/docs/agents/usertest-droplet.md +++ b/docs/agents/usertest-droplet.md @@ -19,7 +19,8 @@ This page is the short runbook, and what needs whose OK. | --- | --- | --- | | `usertest/page/` only | `deploy.sh` | none | | an app's source | bump `VERSIONS` in `usertest/catalog.mjs`, `catalog.mjs`, `check-live.mjs`, `deploy.sh` | none | -| `usertest/moderator/` | `deploy.sh` | moderator (`moderator/run.sh`) | +| `usertest/sample-data/`, or a fixture it imports | bump `SAMPLE_VERSION` in `usertest/catalog.mjs`, `catalog.mjs`, `check-live.mjs`, `deploy.sh` | none | +| `usertest/moderator/` (session plans included) | `deploy.sh` | moderator (`moderator/run.sh`) | | `/etc/*.env` on the droplet | none | the container that reads it | | `usertest/collector/` | `deploy.sh` | collector (`collector/run.sh`) | | atomic-server version or plugin routes | `deploy.sh` if `server.sh` changed | atomic-server (`server.sh`) | @@ -69,7 +70,9 @@ ssh root@178.62.223.35 USERTEST_PLUGIN_ROUTES=read-write sh /opt/usertest/server Issues go to the private `ontola/usertest-findings`. Nothing is public until Michiel labels a finding `approved`. - **Before a page PR:** `node usertest/e2e/run.mjs` (headless, fake media; - not in CI). Never open the page in Michiel's browser to test it (#227 + not in CI). For `usertest/sample-data/` or `catalog.mjs`: + `node --test usertest/sample-data/samples.test.mjs` and + `node usertest/e2e/samples.mjs` (the pinned atomic-server; not in CI). Never open the page in Michiel's browser to test it (#227 rule 9). ## The deploy workflow diff --git a/integrations/money/fixtures/usertest/acme-studio-2026-08.camt053.xml b/integrations/money/fixtures/usertest/acme-studio-2026-08.camt053.xml new file mode 100644 index 000000000..48714f268 --- /dev/null +++ b/integrations/money/fixtures/usertest/acme-studio-2026-08.camt053.xml @@ -0,0 +1,533 @@ + + + + + ACME-CAMT-8 + 2026-09-15T06:00:00 + + + ACME-8 + 8 + 2026-09-15T06:00:00 + + NL00BANK0000000000 + EUR + Acme Studio + + + OPBD + 8412.50 + CRDT +
2026-08-01
+
+ + CLBD + 11783.88 + CRDT +
2026-09-15
+
+ + 1850.00 + DBIT + BOOK +
2026-08-03
+
2026-08-03
+ ACME2026080301 + PMNTICDTESCT + + + NOTPROVIDED + De Werkplaats Verhuur BV + Huur augustus 2026 unit 4 + + +
+ + 14.99 + DBIT + BOOK +
2026-08-03
+
2026-08-03
+ ACME2026080302 + PMNTIDDTESDD + + + NOTPROVIDED + Pixelboard BV + Pixelboard Team abonnement augustus + + +
+ + 2420.00 + CRDT + BOOK +
2026-08-04
+
2026-08-04
+ ACME2026080401 + PMNTRCDTESCT + + + NOTPROVIDED + Bakkerij Zonnig BV + Factuur AS-2026-031 huisstijl + + +
+ + 42.35 + DBIT + BOOK +
2026-08-05
+
2026-08-05
+ ACME2026080501 + PMNTICDTESCT + + + NOTPROVIDED + Koffiebranderij De Boon + Bonen kantoor 3 kg + + +
+ + 28.90 + DBIT + BOOK +
2026-08-06
+
2026-08-06
+ ACME2026080601 + PMNTCCRDPOSD + + + NOTPROVIDED + NS Reizigers + Treinkaartje Utrecht-Rotterdam v.v. + + +
+ + 640.00 + DBIT + BOOK +
2026-08-07
+
2026-08-07
+ ACME2026080701 + PMNTICDTESCT + + + NOTPROVIDED + Lotte Visser + Freelance illustratie juli 2026 + + +
+ + 39.50 + DBIT + BOOK +
2026-08-10
+
2026-08-10
+ ACME2026081001 + PMNTIDDTESDD + + + NOTPROVIDED + Belnet Mobiel + Mobiel abonnement augustus + + +
+ + 45.12 + DBIT + BOOK +
2026-08-11
+
2026-08-11
+ ACME2026081101 + PMNTICDTESCT + + + NOTPROVIDED + Fontfoundry Inc. + Font licence Halcyon Sans, 2 seatsUSD 49.00 rate 0.9208 EUR 45.12 + + +
+ + 968.00 + CRDT + BOOK +
2026-08-12
+
2026-08-12
+ ACME2026081201 + PMNTRCDTESCT + + + NOTPROVIDED + Stichting Groen Plein + Factuur AS-2026-032 website onderhoud + + +
+ + 18.75 + DBIT + BOOK +
2026-08-13
+
2026-08-13
+ ACME2026081301 + PMNTCCRDPOSD + + + NOTPROVIDED + Drukkerij Kleur & Co + Visitekaartjes proefdruk + + +
+ + 118.34 + DBIT + BOOK +
2026-08-14
+
2026-08-14
+ ACME2026081401 + PMNTIDDTESDD + + + NOTPROVIDED + Verzekeraar Veilig NV + SEPA Incasso algemeen doorlopendIncassant: NL00ZZZ000000000000Machtiging: VV-2024-118833 bedrijfsaansprakelijkheidOmschrijving: Premie bedrijfsaansprakelijkheidsverzekeringperiode 01-08-2026 t/m 31-08-2026 polis 4410-2291-07IBAN: NL00BANK0000000099 Kenmerk: 2026081400118833 + + +
+ + 24.50 + DBIT + BOOK +
2026-08-17
+
2026-08-17
+ ACME2026081701 + PMNTCCRDPOSD + + + NOTPROVIDED + Lunchroom Het Plein + Lunch klantoverleg + + +
+ + 18.75 + CRDT + BOOK +
2026-08-18
+
2026-08-18
+ ACME2026081801 + PMNTRCDTESCT + + + NOTPROVIDED + Drukkerij Kleur & Co + Terugbetaling proefdruk, dubbel gefactureerd + + +
+ + 8.99 + DBIT + BOOK +
2026-08-19
+
2026-08-19
+ ACME2026081901 + PMNTIDDTESDD + + + NOTPROVIDED + Hostly Hosting + Webhosting acmestudio.example augustus + + +
+ + 3630.00 + CRDT + BOOK +
2026-08-20
+
2026-08-20
+ ACME2026082001 + PMNTRCDTESCT + + + NOTPROVIDED + Fietsenmaker Snel VOF + Factuur AS-2026-033 webshop fase 1 + + +
+ + 76.80 + DBIT + BOOK +
2026-08-21
+
2026-08-21
+ ACME2026082101 + PMNTCCRDPOSD + + + NOTPROVIDED + Bouwmarkt Hamer + Kantoorspullen en verlichting + + +
+ + 520.00 + DBIT + BOOK +
2026-08-24
+
2026-08-24
+ ACME2026082401 + PMNTICDTESCT + + + NOTPROVIDED + Ravi Brouwer + Freelance development juli 2026 + + +
+ + 12.50 + DBIT + BOOK +
2026-08-25
+
2026-08-25
+ ACME2026082501 + PMNTCCRDPOSD + + + NOTPROVIDED + Bank + Kosten zakelijke rekening augustus + + +
+ + 726.00 + CRDT + BOOK +
2026-08-27
+
2026-08-27
+ ACME2026082701 + PMNTRCDTESCT + + + NOTPROVIDED + Theater De Kleine Zaal + Factuur AS-2026-034 affiches seizoen + + +
+ + 275.00 + DBIT + BOOK +
2026-08-28
+
2026-08-28
+ ACME2026082801 + PMNTICDTESCT + + + NOTPROVIDED + Belastingdienst + Betalingskenmerk 0000 0000 0000 0001 btw Q2 + + +
+ + 31.00 + DBIT + BOOK +
2026-08-31
+
2026-08-31
+ ACME2026083101 + PMNTCCRDPOSD + + + NOTPROVIDED + Tankstation Noord + Tanken bestelauto + + +
+ + 1850.00 + DBIT + BOOK +
2026-09-01
+
2026-09-01
+ ACME2026090101 + PMNTICDTESCT + + + NOTPROVIDED + De Werkplaats Verhuur BV + Huur september 2026 unit 4 + + +
+ + 14.99 + DBIT + BOOK +
2026-09-01
+
2026-09-01
+ ACME2026090102 + PMNTIDDTESDD + + + NOTPROVIDED + Pixelboard BV + Pixelboard Team abonnement september + + +
+ + 1512.50 + CRDT + BOOK +
2026-09-02
+
2026-09-02
+ ACME2026090201 + PMNTRCDTESCT + + + NOTPROVIDED + Bakkerij Zonnig BV + Factuur AS-2026-035 verpakkingen + + +
+ + 28.90 + DBIT + BOOK +
2026-09-03
+
2026-09-03
+ ACME2026090301 + PMNTCCRDPOSD + + + NOTPROVIDED + NS Reizigers + Treinkaartje Utrecht-Amsterdam v.v. + + +
+ + 640.00 + DBIT + BOOK +
2026-09-07
+
2026-09-07
+ ACME2026090701 + PMNTICDTESCT + + + NOTPROVIDED + Lotte Visser + Freelance illustratie augustus 2026 + + +
+ + 39.50 + DBIT + BOOK +
2026-09-08
+
2026-09-08
+ ACME2026090801 + PMNTIDDTESDD + + + NOTPROVIDED + Belnet Mobiel + Mobiel abonnement september + + +
+ + 16.40 + DBIT + BOOK +
2026-09-09
+
2026-09-09
+ ACME2026090901 + PMNTCCRDPOSD + + + NOTPROVIDED + Lunchroom Het Plein + Lunch team + + +
+ + 484.00 + CRDT + BOOK +
2026-09-10
+
2026-09-10
+ ACME2026091001 + PMNTRCDTESCT + + + NOTPROVIDED + Stichting Groen Plein + Factuur AS-2026-036 nieuwsbrief + + +
+ + 8.99 + DBIT + BOOK +
2026-09-14
+
2026-09-14
+ ACME2026091401 + PMNTIDDTESDD + + + NOTPROVIDED + Hostly Hosting + Webhosting acmestudio.example september + + +
+ + 42.35 + DBIT + BOOK +
2026-09-15
+
2026-09-15
+ ACME2026091501 + PMNTICDTESCT + + + NOTPROVIDED + Koffiebranderij De Boon + Bonen kantoor 3 kg + + +
+ + 23.80 + DBIT + PDNG +
2026-09-15
+
+
+
+
diff --git a/integrations/money/fixtures/usertest/acme-studio-2026-08.mt940 b/integrations/money/fixtures/usertest/acme-studio-2026-08.mt940 new file mode 100644 index 000000000..9def5ba78 --- /dev/null +++ b/integrations/money/fixtures/usertest/acme-studio-2026-08.mt940 @@ -0,0 +1,104 @@ +:20:ACME260915 +:25:NL00BANK0000000000 +:28C:8/1 +:60F:C260801EUR8412,50 +:61:2608030803D1850,00NTRFNONREF//ACME2026080301 +:86:De Werkplaats Verhuur BV +Huur augustus 2026 unit 4 +:61:2608030803D14,99NDDTNONREF//ACME2026080302 +:86:Pixelboard BV +Pixelboard Team abonnement augustus +:61:2608040804C2420,00NTRFNONREF//ACME2026080401 +:86:Bakkerij Zonnig BV +Factuur AS-2026-031 huisstijl +:61:2608050805D42,35NTRFNONREF//ACME2026080501 +:86:Koffiebranderij De Boon +Bonen kantoor 3 kg +:61:2608060806D28,90NMSCNONREF//ACME2026080601 +:86:NS Reizigers +Treinkaartje Utrecht-Rotterdam v.v. +:61:2608070807D640,00NTRFNONREF//ACME2026080701 +:86:Lotte Visser +Freelance illustratie juli 2026 +:61:2608100810D39,50NDDTNONREF//ACME2026081001 +:86:Belnet Mobiel +Mobiel abonnement augustus +:61:2608110811D45,12NTRFNONREF//ACME2026081101 +:86:Fontfoundry Inc. +Font licence Halcyon Sans, 2 seats +USD 49.00 rate 0.9208 EUR 45.12 +:61:2608120812C968,00NTRFNONREF//ACME2026081201 +:86:Stichting Groen Plein +Factuur AS-2026-032 website onderhoud +:61:2608130813D18,75NMSCNONREF//ACME2026081301 +:86:Drukkerij Kleur & Co +Visitekaartjes proefdruk +:61:2608140814D118,34NDDTNONREF//ACME2026081401 +:86:Verzekeraar Veilig NV +SEPA Incasso algemeen doorlopend +Incassant: NL00ZZZ000000000000 +Machtiging: VV-2024-118833 bedrijfsaansprakelijkheid +Omschrijving: Premie bedrijfsaansprakelijkheidsverzekering +periode 01-08-2026 t/m 31-08-2026 polis 4410-2291-07 +IBAN: NL00BANK0000000099 Kenmerk: 2026081400118833 +:61:2608170817D24,50NMSCNONREF//ACME2026081701 +:86:Lunchroom Het Plein +Lunch klantoverleg +:61:2608180818C18,75NTRFNONREF//ACME2026081801 +:86:Drukkerij Kleur & Co +Terugbetaling proefdruk, dubbel gefactureerd +:61:2608190819D8,99NDDTNONREF//ACME2026081901 +:86:Hostly Hosting +Webhosting acmestudio.example augustus +:61:2608200820C3630,00NTRFNONREF//ACME2026082001 +:86:Fietsenmaker Snel VOF +Factuur AS-2026-033 webshop fase 1 +:61:2608210821D76,80NMSCNONREF//ACME2026082101 +:86:Bouwmarkt Hamer +Kantoorspullen en verlichting +:61:2608240824D520,00NTRFNONREF//ACME2026082401 +:86:Ravi Brouwer +Freelance development juli 2026 +:61:2608250825D12,50NMSCNONREF//ACME2026082501 +:86:Bank +Kosten zakelijke rekening augustus +:61:2608270827C726,00NTRFNONREF//ACME2026082701 +:86:Theater De Kleine Zaal +Factuur AS-2026-034 affiches seizoen +:61:2608280828D275,00NTRFNONREF//ACME2026082801 +:86:Belastingdienst +Betalingskenmerk 0000 0000 0000 0001 btw Q2 +:61:2608310831D31,00NMSCNONREF//ACME2026083101 +:86:Tankstation Noord +Tanken bestelauto +:61:2609010901D1850,00NTRFNONREF//ACME2026090101 +:86:De Werkplaats Verhuur BV +Huur september 2026 unit 4 +:61:2609010901D14,99NDDTNONREF//ACME2026090102 +:86:Pixelboard BV +Pixelboard Team abonnement september +:61:2609020902C1512,50NTRFNONREF//ACME2026090201 +:86:Bakkerij Zonnig BV +Factuur AS-2026-035 verpakkingen +:61:2609030903D28,90NMSCNONREF//ACME2026090301 +:86:NS Reizigers +Treinkaartje Utrecht-Amsterdam v.v. +:61:2609070907D640,00NTRFNONREF//ACME2026090701 +:86:Lotte Visser +Freelance illustratie augustus 2026 +:61:2609080908D39,50NDDTNONREF//ACME2026090801 +:86:Belnet Mobiel +Mobiel abonnement september +:61:2609090909D16,40NMSCNONREF//ACME2026090901 +:86:Lunchroom Het Plein +Lunch team +:61:2609100910C484,00NTRFNONREF//ACME2026091001 +:86:Stichting Groen Plein +Factuur AS-2026-036 nieuwsbrief +:61:2609140914D8,99NDDTNONREF//ACME2026091401 +:86:Hostly Hosting +Webhosting acmestudio.example september +:61:2609150915D42,35NTRFNONREF//ACME2026091501 +:86:Koffiebranderij De Boon +Bonen kantoor 3 kg +:62F:C260915EUR11783,88 diff --git a/integrations/money/fixtures/usertest/acme-studio-2026-09.mt940 b/integrations/money/fixtures/usertest/acme-studio-2026-09.mt940 new file mode 100644 index 000000000..d06ce7616 --- /dev/null +++ b/integrations/money/fixtures/usertest/acme-studio-2026-09.mt940 @@ -0,0 +1,85 @@ +:20:ACME260930 +:25:NL00BANK0000000000 +:28C:9/1 +:60F:C260901EUR12428,51 +:61:2609010901D1850,00NTRFNONREF//ACME2026090101 +:86:De Werkplaats Verhuur BV +Huur september 2026 unit 4 +:61:2609010901D14,99NDDTNONREF//ACME2026090102 +:86:Pixelboard BV +Pixelboard Team abonnement september +:61:2609020902C1512,50NTRFNONREF//ACME2026090201 +:86:Bakkerij Zonnig BV +Factuur AS-2026-035 verpakkingen +:61:2609030903D28,90NMSCNONREF//ACME2026090301 +:86:NS Reizigers +Treinkaartje Utrecht-Amsterdam v.v. +:61:2609070907D640,00NTRFNONREF//ACME2026090701 +:86:Lotte Visser +Freelance illustratie augustus 2026 +:61:2609080908D39,50NDDTNONREF//ACME2026090801 +:86:Belnet Mobiel +Mobiel abonnement september +:61:2609090909D16,40NMSCNONREF//ACME2026090901 +:86:Lunchroom Het Plein +Lunch team +:61:2609100910C484,00NTRFNONREF//ACME2026091001 +:86:Stichting Groen Plein +Factuur AS-2026-036 nieuwsbrief +:61:2609140914D8,99NDDTNONREF//ACME2026091401 +:86:Hostly Hosting +Webhosting acmestudio.example september +:61:2609150915D42,35NTRFNONREF//ACME2026091501 +:86:Koffiebranderij De Boon +Bonen kantoor 3 kg +:61:2609160916C2117,50NTRFNONREF//ACME2026091601 +:86:Fietsenmaker Snel VOF +Factuur AS-2026-037 webshop fase 2 +:61:2609170917D59,90NMSCNONREF//ACME2026091701 +:86:Kantoorwinkel Pen +Printerpapier en inkt +:61:2609180918D520,00NTRFNONREF//ACME2026091801 +:86:Ravi Brouwer +Freelance development augustus 2026 +:61:2609210921D118,34NDDTNONREF//ACME2026092101 +:86:Verzekeraar Veilig NV +SEPA Incasso algemeen doorlopend +Incassant: NL00ZZZ000000000000 +Machtiging: VV-2024-118833 bedrijfsaansprakelijkheid +Omschrijving: Premie bedrijfsaansprakelijkheidsverzekering +periode 01-09-2026 t/m 30-09-2026 polis 4410-2291-07 +IBAN: NL00BANK0000000099 Kenmerk: 2026092100118833 +:61:2609220922D24,50NMSCNONREF//ACME2026092201 +:86:Lunchroom Het Plein +Lunch klantoverleg +:61:2609230923C605,00NTRFNONREF//ACME2026092301 +:86:Theater De Kleine Zaal +Factuur AS-2026-038 programmaboekje +:61:2609240924D31,00NMSCNONREF//ACME2026092401 +:86:Tankstation Noord +Tanken bestelauto +:61:2609250925D12,50NMSCNONREF//ACME2026092501 +:86:Bank +Kosten zakelijke rekening september +:61:2609250925D149,00NTRFNONREF//ACME2026092502 +:86:Opleidingen Online BV +Cursus typografie, 1 deelnemer +:61:2609280928C302,50NTRFNONREF//ACME2026092801 +:86:Huisartsenpraktijk Lindeboom +Factuur AS-2026-039 bewegwijzering +:61:2609290929D80,00NTRFNONREF//ACME2026092901 +:86:Ravi Brouwer +Onkosten treinreizen september +:61:2609300930D21,90NMSCNONREF//ACME2026093001 +:86:Koffiebar Station +Koffie en broodjes workshop +:61:2609300930D60,50NDDTNONREF//ACME2026093002 +:86:Belnet Internet +Zakelijk internet september +:61:2609300930D35,00NTRFNONREF//ACME2026093003 +:86:Lotte Visser +Reiskosten augustus +:61:2609300930D14,99NMSCNONREF//ACME2026093004 +:86:Webwinkel Kabel +USB-C kabels 3 stuks +:62F:C260930EUR13681,25 diff --git a/integrations/money/fixtures/usertest/generate.mjs b/integrations/money/fixtures/usertest/generate.mjs new file mode 100644 index 000000000..46af13a63 --- /dev/null +++ b/integrations/money/fixtures/usertest/generate.mjs @@ -0,0 +1,494 @@ +#!/usr/bin/env node +/** + * Writes the sample bank statements for moderated user testing (#196), so a + * tester can try the Money app without showing their own bank export: + * + * node integrations/money/fixtures/usertest/generate.mjs # write + * node integrations/money/fixtures/usertest/generate.mjs --check # compare + * + * Everything here is invented: the studio, its account number + * (NL00BANK0000000000, not a valid IBAN), the counterparties and the + * references. `usertest/catalog.mjs` copies the written files to the catalog + * host's `samples/money/`; `../../usertest-samples.test.ts` parses them. + * + * - `acme-studio-2026-08.mt940` and `acme-studio-2026-08.camt053.xml`: the + * same 31 bookings from 1 August to 15 September 2026, once per format. + * - `acme-studio-2026-09.mt940`: 1 to 30 September, 25 bookings. The first + * ten (1 to 15 September) are the same bookings with the same bank + * references, so importing it after the first file adds only the 15 new + * ones. + * + * It includes a refund, a payment in US dollars (booked in euros, with the + * dollar amount and rate in the description), a direct debit with a long + * bank description over several lines, and a pending card payment in the + * camt.053 file, which is left out of the booked balances. + */ +import { readFileSync, writeFileSync } from 'node:fs'; +import { dirname, join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const here = dirname(fileURLToPath(import.meta.url)); +const ACCOUNT = 'NL00BANK0000000000'; +const HOLDER = 'Acme Studio'; + +/** + * [booking date, amount in cents (negative is out), MT940 code, counterparty, + * description lines]. The bank reference is derived from the date and order. + */ +const BOOKINGS = [ + [ + '2026-08-03', + -185000, + 'NTRF', + 'De Werkplaats Verhuur BV', + ['Huur augustus 2026 unit 4'], + ], + [ + '2026-08-03', + -1499, + 'NDDT', + 'Pixelboard BV', + ['Pixelboard Team abonnement augustus'], + ], + [ + '2026-08-04', + 242000, + 'NTRF', + 'Bakkerij Zonnig BV', + ['Factuur AS-2026-031 huisstijl'], + ], + [ + '2026-08-05', + -4235, + 'NTRF', + 'Koffiebranderij De Boon', + ['Bonen kantoor 3 kg'], + ], + [ + '2026-08-06', + -2890, + 'NMSC', + 'NS Reizigers', + ['Treinkaartje Utrecht-Rotterdam v.v.'], + ], + [ + '2026-08-07', + -64000, + 'NTRF', + 'Lotte Visser', + ['Freelance illustratie juli 2026'], + ], + [ + '2026-08-10', + -3950, + 'NDDT', + 'Belnet Mobiel', + ['Mobiel abonnement augustus'], + ], + [ + '2026-08-11', + -4512, + 'NTRF', + 'Fontfoundry Inc.', + ['Font licence Halcyon Sans, 2 seats', 'USD 49.00 rate 0.9208 EUR 45.12'], + ], + [ + '2026-08-12', + 96800, + 'NTRF', + 'Stichting Groen Plein', + ['Factuur AS-2026-032 website onderhoud'], + ], + [ + '2026-08-13', + -1875, + 'NMSC', + 'Drukkerij Kleur & Co', + ['Visitekaartjes proefdruk'], + ], + [ + '2026-08-14', + -11834, + 'NDDT', + 'Verzekeraar Veilig NV', + [ + 'SEPA Incasso algemeen doorlopend', + 'Incassant: NL00ZZZ000000000000', + 'Machtiging: VV-2024-118833 bedrijfsaansprakelijkheid', + 'Omschrijving: Premie bedrijfsaansprakelijkheidsverzekering', + 'periode 01-08-2026 t/m 31-08-2026 polis 4410-2291-07', + 'IBAN: NL00BANK0000000099 Kenmerk: 2026081400118833', + ], + ], + ['2026-08-17', -2450, 'NMSC', 'Lunchroom Het Plein', ['Lunch klantoverleg']], + [ + '2026-08-18', + 1875, + 'NTRF', + 'Drukkerij Kleur & Co', + ['Terugbetaling proefdruk, dubbel gefactureerd'], + ], + [ + '2026-08-19', + -899, + 'NDDT', + 'Hostly Hosting', + ['Webhosting acmestudio.example augustus'], + ], + [ + '2026-08-20', + 363000, + 'NTRF', + 'Fietsenmaker Snel VOF', + ['Factuur AS-2026-033 webshop fase 1'], + ], + [ + '2026-08-21', + -7680, + 'NMSC', + 'Bouwmarkt Hamer', + ['Kantoorspullen en verlichting'], + ], + [ + '2026-08-24', + -52000, + 'NTRF', + 'Ravi Brouwer', + ['Freelance development juli 2026'], + ], + ['2026-08-25', -1250, 'NMSC', 'Bank', ['Kosten zakelijke rekening augustus']], + [ + '2026-08-27', + 72600, + 'NTRF', + 'Theater De Kleine Zaal', + ['Factuur AS-2026-034 affiches seizoen'], + ], + [ + '2026-08-28', + -27500, + 'NTRF', + 'Belastingdienst', + ['Betalingskenmerk 0000 0000 0000 0001 btw Q2'], + ], + ['2026-08-31', -3100, 'NMSC', 'Tankstation Noord', ['Tanken bestelauto']], + // 1 to 15 September: in both files. + [ + '2026-09-01', + -185000, + 'NTRF', + 'De Werkplaats Verhuur BV', + ['Huur september 2026 unit 4'], + ], + [ + '2026-09-01', + -1499, + 'NDDT', + 'Pixelboard BV', + ['Pixelboard Team abonnement september'], + ], + [ + '2026-09-02', + 151250, + 'NTRF', + 'Bakkerij Zonnig BV', + ['Factuur AS-2026-035 verpakkingen'], + ], + [ + '2026-09-03', + -2890, + 'NMSC', + 'NS Reizigers', + ['Treinkaartje Utrecht-Amsterdam v.v.'], + ], + [ + '2026-09-07', + -64000, + 'NTRF', + 'Lotte Visser', + ['Freelance illustratie augustus 2026'], + ], + [ + '2026-09-08', + -3950, + 'NDDT', + 'Belnet Mobiel', + ['Mobiel abonnement september'], + ], + ['2026-09-09', -1640, 'NMSC', 'Lunchroom Het Plein', ['Lunch team']], + [ + '2026-09-10', + 48400, + 'NTRF', + 'Stichting Groen Plein', + ['Factuur AS-2026-036 nieuwsbrief'], + ], + [ + '2026-09-14', + -899, + 'NDDT', + 'Hostly Hosting', + ['Webhosting acmestudio.example september'], + ], + [ + '2026-09-15', + -4235, + 'NTRF', + 'Koffiebranderij De Boon', + ['Bonen kantoor 3 kg'], + ], + // 16 to 30 September: only in the second file. + [ + '2026-09-16', + 211750, + 'NTRF', + 'Fietsenmaker Snel VOF', + ['Factuur AS-2026-037 webshop fase 2'], + ], + ['2026-09-17', -5990, 'NMSC', 'Kantoorwinkel Pen', ['Printerpapier en inkt']], + [ + '2026-09-18', + -52000, + 'NTRF', + 'Ravi Brouwer', + ['Freelance development augustus 2026'], + ], + [ + '2026-09-21', + -11834, + 'NDDT', + 'Verzekeraar Veilig NV', + [ + 'SEPA Incasso algemeen doorlopend', + 'Incassant: NL00ZZZ000000000000', + 'Machtiging: VV-2024-118833 bedrijfsaansprakelijkheid', + 'Omschrijving: Premie bedrijfsaansprakelijkheidsverzekering', + 'periode 01-09-2026 t/m 30-09-2026 polis 4410-2291-07', + 'IBAN: NL00BANK0000000099 Kenmerk: 2026092100118833', + ], + ], + ['2026-09-22', -2450, 'NMSC', 'Lunchroom Het Plein', ['Lunch klantoverleg']], + [ + '2026-09-23', + 60500, + 'NTRF', + 'Theater De Kleine Zaal', + ['Factuur AS-2026-038 programmaboekje'], + ], + ['2026-09-24', -3100, 'NMSC', 'Tankstation Noord', ['Tanken bestelauto']], + [ + '2026-09-25', + -1250, + 'NMSC', + 'Bank', + ['Kosten zakelijke rekening september'], + ], + [ + '2026-09-25', + -14900, + 'NTRF', + 'Opleidingen Online BV', + ['Cursus typografie, 1 deelnemer'], + ], + [ + '2026-09-28', + 30250, + 'NTRF', + 'Huisartsenpraktijk Lindeboom', + ['Factuur AS-2026-039 bewegwijzering'], + ], + [ + '2026-09-29', + -8000, + 'NTRF', + 'Ravi Brouwer', + ['Onkosten treinreizen september'], + ], + [ + '2026-09-30', + -2190, + 'NMSC', + 'Koffiebar Station', + ['Koffie en broodjes workshop'], + ], + [ + '2026-09-30', + -6050, + 'NDDT', + 'Belnet Internet', + ['Zakelijk internet september'], + ], + ['2026-09-30', -3500, 'NTRF', 'Lotte Visser', ['Reiskosten augustus']], + ['2026-09-30', -1499, 'NMSC', 'Webwinkel Kabel', ['USB-C kabels 3 stuks']], +]; + +const OPENING = 841250; // 1 August 2026, in cents + +/** Bookings with their bank reference, in order. */ +const ALL = (() => { + const perDay = new Map(); + + return BOOKINGS.map(([date, cents, code, party, lines]) => { + const n = (perDay.get(date) ?? 0) + 1; + perDay.set(date, n); + const reference = `ACME${date.replaceAll('-', '')}${String(n).padStart(2, '0')}`; + + return { date, cents, code, party, lines, reference }; + }); +})(); + +const between = (from, to) => ALL.filter(b => b.date >= from && b.date <= to); +const balanceBefore = date => + OPENING + ALL.filter(b => b.date < date).reduce((t, b) => t + b.cents, 0); +const total = rows => rows.reduce((t, b) => t + b.cents, 0); + +const euros = (cents, separator) => { + const abs = Math.abs(cents); + + return `${Math.floor(abs / 100)}${separator}${String(abs % 100).padStart(2, '0')}`; +}; + +const yymmdd = date => date.slice(2).replaceAll('-', ''); +const mmdd = date => date.slice(5).replaceAll('-', ''); +const sign = cents => (cents < 0 ? 'D' : 'C'); + +/** One MT940 statement. Narrative lines are at most 65 characters. */ +function mt940({ number, from, to }) { + const rows = between(from, to); + const opening = balanceBefore(from); + const closing = opening + total(rows); + const lines = [ + `:20:ACME${yymmdd(to)}`, + `:25:${ACCOUNT}`, + `:28C:${number}/1`, + `:60F:${sign(opening)}${yymmdd(from)}EUR${euros(opening, ',')}`, + ]; + + for (const b of rows) { + lines.push( + `:61:${yymmdd(b.date)}${mmdd(b.date)}${sign(b.cents)}${euros(b.cents, ',')}${b.code}NONREF//${b.reference}`, + ); + const narrative = [b.party, ...b.lines]; + for (const line of narrative) + if (line.length > 65) throw new Error(`MT940 line too long: ${line}`); + lines.push(`:86:${narrative[0]}`, ...narrative.slice(1)); + } + + lines.push(`:62F:${sign(closing)}${yymmdd(to)}EUR${euros(closing, ',')}`); + + return lines.join('\r\n') + '\r\n'; +} + +const xml = text => + text.replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>'); + +/** One camt.053 statement, plus a pending entry outside the balances. */ +function camt053({ number, from, to }) { + const rows = between(from, to); + const opening = balanceBefore(from); + const closing = opening + total(rows); + const bal = (code, cents, date) => ` + ${code} + ${euros(cents, '.')} + ${cents < 0 ? 'DBIT' : 'CRDT'} +
${date}
+
`; + + const entry = b => { + const out = b.cents < 0; + const party = out + ? `${xml(b.party)}` + : `${xml(b.party)}`; + const family = + b.code === 'NDDT' + ? 'PMNTIDDTESDD' + : b.code === 'NMSC' + ? 'PMNTCCRDPOSD' + : `PMNT${out ? 'ICDT' : 'RCDT'}ESCT`; + + return ` + ${euros(b.cents, '.')} + ${out ? 'DBIT' : 'CRDT'} + BOOK +
${b.date}
+
${b.date}
+ ${b.reference} + ${family} + + + NOTPROVIDED + ${party} + ${b.lines.map(l => `${xml(l)}`).join('')} + + +
`; + }; + + return ` + + + + ACME-CAMT-${number} + ${to}T06:00:00 + + + ACME-${number} + ${number} + ${to}T06:00:00 + + ${ACCOUNT} + EUR + ${HOLDER} + +${bal('OPBD', opening, from)} +${bal('CLBD', closing, to)} +${rows.map(entry).join('\n')} + + 23.80 + DBIT + PDNG +
${to}
+
+
+
+
+`; +} + +const FIRST = { number: '8', from: '2026-08-01', to: '2026-09-15' }; +const SECOND = { number: '9', from: '2026-09-01', to: '2026-09-30' }; + +/** File name -> contents. */ +export const FILES = { + 'acme-studio-2026-08.mt940': mt940(FIRST), + 'acme-studio-2026-08.camt053.xml': camt053(FIRST), + 'acme-studio-2026-09.mt940': mt940(SECOND), +}; + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + const check = process.argv.includes('--check'); + let stale = 0; + + for (const [name, text] of Object.entries(FILES)) { + const file = join(here, name); + + if (!check) { + writeFileSync(file, text); + console.info(`wrote ${name}`); + continue; + } + + let current = ''; + + try { + current = readFileSync(file, 'utf8'); + } catch {} + + if (current !== text) { + stale++; + console.error(`${name} is out of date; run generate.mjs`); + } + } + + if (stale) process.exit(1); +} diff --git a/integrations/money/usertest-samples.test.ts b/integrations/money/usertest-samples.test.ts new file mode 100644 index 000000000..0d42a0d11 --- /dev/null +++ b/integrations/money/usertest-samples.test.ts @@ -0,0 +1,73 @@ +// @wc-ignore-file +/** + * The sample statements moderated user testing serves to testers (#196, + * `fixtures/usertest/`): they are current with their generator, both readers + * accept them, the two formats hold the same bookings, and the second file + * overlaps the first only by bank reference. + */ +import { readFileSync } from 'node:fs'; +import { describe, expect, it } from 'vitest'; +import { FILES } from './fixtures/usertest/generate.mjs'; +import { entries } from './identity'; +import { parseBankStatement } from './statement'; + +const read = (name: string) => + readFileSync(new URL(`./fixtures/usertest/${name}`, import.meta.url), 'utf8'); + +describe('user-testing sample statements', () => { + it('are what generate.mjs writes', () => { + for (const [name, text] of Object.entries(FILES as Record)) + expect(read(name), name).toBe(text); + }); + + it('parse and reconcile in both formats, with the same bookings', () => { + const mt940 = parseBankStatement(read('acme-studio-2026-08.mt940')); + const camt = parseBankStatement(read('acme-studio-2026-08.camt053.xml')); + expect(mt940.format).toBe('mt940'); + expect(camt.format).toBe('camt053'); + + const [a] = mt940.statements; + const [b] = camt.statements; + expect(a.account).toBe('NL00BANK0000000000'); + expect([a.start, a.end, a.opening, a.closing]).toEqual([ + '2026-08-01', + '2026-09-15', + '8412.5', + '11783.88', + ]); + expect([b.start, b.end, b.opening, b.closing]).toEqual([ + a.start, + a.end, + a.opening, + a.closing, + ]); + // The pending camt.053 entry is left out. + expect(b.transactions).toHaveLength(31); + expect( + a.transactions.map(t => [t.date, t.amount, t.bankReference]), + ).toEqual(b.transactions.map(t => [t.date, t.amount, t.bankReference])); + expect(a.transactions.find(t => t.amount === '18.75')?.description).toMatch( + /Terugbetaling/, + ); + expect( + a.transactions.find(t => t.description.includes('USD 49.00'))?.amount, + ).toBe('-45.12'); + expect( + a.transactions + .find(t => t.description.includes('Machtiging')) + ?.description.split('\n').length, + ).toBe(7); + }); + + it('overlap by bank reference: the September file adds 15 bookings', () => { + const first = parseBankStatement(read('acme-studio-2026-08.mt940')); + const second = parseBankStatement(read('acme-studio-2026-09.mt940')); + const known = new Set( + entries(first.format, first.statements).map(e => e.identity), + ); + const next = entries(second.format, second.statements); + expect(next).toHaveLength(25); + expect(next.filter(e => !known.has(e.identity))).toHaveLength(15); + expect(second.statements[0].opening).toBe('12428.51'); + }); +}); diff --git a/usertest/Caddyfile b/usertest/Caddyfile index efccb20a9..af54329cc 100644 --- a/usertest/Caddyfile +++ b/usertest/Caddyfile @@ -33,13 +33,17 @@ plugins.{$BASE_DOMAIN} { } } -# The test catalog and the drive app modules it points at (catalog.mjs). +# The test catalog, the drive app modules it points at and the sample files +# for sessions (catalog.mjs). # The data-browser fetches the catalog cross-origin; app modules are # downloaded by the host and checked against their SRI hash. catalog.{$BASE_DOMAIN} { root * /srv/catalog header Access-Control-Allow-Origin * header Cache-Control "no-cache" + # Sample files for sessions (moderator/sessions/*.md): a download, not a + # page, whatever the browser makes of .mt940 or .xml. + header /samples/* Content-Disposition attachment file_server } diff --git a/usertest/README.md b/usertest/README.md index d59d6ab5c..4afe53105 100644 --- a/usertest/README.md +++ b/usertest/README.md @@ -30,6 +30,17 @@ toggle. The published catalog keeps these disabled until launch. Apps not yet in `apps/` are built from this checkout and served from the droplet. Pets uses its published module. +It also adds a sample-data entry for four of them (#196): "Google Calendar +(sample data)", "GitHub issues (sample data)", "Clockify timesheets (sample +data)" and "Notion (sample data)". Each is the same built app, wrapped so +that its provider is answered by invented data in the app's own frame, +already connected, and nothing reaches the provider. Testers without an +account, or sessions for which we have no account to lend, use these with +the `-sample` session plans. See [`sample-data/README.md`](sample-data/README.md). +The Money app needs no account; `catalog.mjs` also copies its sample bank +statements to `https://catalog./samples/money/`, which the +session page links. + Known limits, as of 2026-09-28: - Pets cannot connect: localthought.io has no `pets` platform (#174). @@ -70,6 +81,9 @@ ssh root@178.62.223.35 sh /opt/usertest/server.sh 178-62-223-35.sslip.io ## Updating an app 1. Change the app, then bump its entry in `VERSIONS` in `catalog.mjs`. + Its sample-data entry, if it has one, follows: its version is the app's + plus `SAMPLE_VERSION`. A change to `sample-data/` or to a fixture it + imports bumps `SAMPLE_VERSION` instead. 2. Run `USERTEST_LOG_URL=https://logs.178-62-223-35.sslip.io/log node usertest/catalog.mjs`, then `sh usertest/deploy.sh root@178.62.223.35`. 3. On Integrations, testers who installed the old version see "Update to @@ -331,6 +345,23 @@ node usertest/e2e/run.mjs CHROMIUM_PATH=/path/to/chromium node usertest/e2e/run.mjs ``` +It also checks that a plan's sample files are linked (for `money`), stay +visible during the session, and are absent for a plan without any. + +The sample-data apps have two checks of their own. The first needs only +Node; the second runs the pinned atomic-server (the layout and binary from +`AGENTS.md`, as for a lane's e2e tier) on ports 19290 to 19292, installs +each "(sample data)" entry from a freshly built catalog into a fresh drive, +runs its first import, and checks an invented record before and after a +reload: + +```sh +node --test usertest/sample-data/samples.test.mjs +node usertest/e2e/samples.mjs # or: … samples.mjs calendar notion +``` + +Neither runs in CI. Both passed on 2026-10-01 at pin `a12b74a6783b`. + The page is in English or Dutch (Nederlands), picked with the buttons at the top, by `&lang=nl` in the invite link, or remembered from a previous visit. The choice switches the page's texts, the speech recognizer, the @@ -461,7 +492,8 @@ sends. Bodies over 1 MB are refused. ## Privacy -Testers connect real accounts. Their data is on the droplet, in the Docker +Testers connect real accounts, unless they use a sample-data app or the +sample bank statements, which hold invented data only. Their data is on the droplet, in the Docker volume `atomic-plugins-store`, and their provider tokens are in localthought.io's database. Error reports can contain what was on screen (titles in messages, URLs), and they stay in `/var/lib/usertest-logs`. diff --git a/usertest/catalog.mjs b/usertest/catalog.mjs index a59755807..1538242ba 100755 --- a/usertest/catalog.mjs +++ b/usertest/catalog.mjs @@ -21,6 +21,14 @@ * apps///ui.js, with the SRI hash the host checks on install. * Pets keeps its published module. * + * With sample data (#196): each app in SAMPLES also gets a second entry, + * " (sample data)", whose module wraps the same built app with + * `sample-data/proxy.mjs` and one of the mock proxy's provider fixtures, so + * it runs on invented data without a provider account (sample-data/README.md). + * Its version is the app's plus SAMPLE_VERSION, so it changes with either. + * The sample bank statements for the Money app + * (integrations/money/fixtures/usertest/) are copied to samples/money/. + * * VERSIONS below is the only thing to edit. Bump an app's version whenever * its build changes: the host offers "Update to " only for a new * version string, and a changed file under an old version fails the @@ -30,7 +38,15 @@ * atomic-server) and each app's dependencies installed (see README.md). */ import { createHash } from 'node:crypto'; -import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'; +import { + copyFileSync, + mkdirSync, + readFileSync, + readdirSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { createRequire } from 'node:module'; import { dirname, resolve } from 'node:path'; import { fileURLToPath, pathToFileURL } from 'node:url'; @@ -70,6 +86,19 @@ const APPS = { timesheets: { base: 'timesheets', row: ['Time entry', 'Time entries'] }, }; +/** + * Apps that also get a sample-data entry, by their id in APPS, with the + * provider fixture under sample-data/. Bump SAMPLE_VERSION whenever + * sample-data/ or a fixture it imports changes. + */ +const SAMPLE_VERSION = 'sample-1'; +const SAMPLES = { + calendar: { provider: 'Google Calendar', name: 'Google Calendar' }, + 'issue-tracker': { provider: 'GitHub', name: 'GitHub issues' }, + timesheets: { provider: 'Clockify', name: 'Clockify timesheets' }, + notion: { provider: 'Notion', name: 'Notion' }, +}; + const LOG_URL = process.env.USERTEST_LOG_URL; if (LOG_URL && !/^https:\/\/[^/]+\/log$/.test(LOG_URL)) throw new Error('USERTEST_LOG_URL must look like https:///log'); @@ -84,6 +113,77 @@ const catalog = JSON.parse( ); const byShortname = name => catalog.find(r => r[A + 'shortname'] === name); +const require = createRequire(resolve(repo, 'browser/package.json')); +const esbuild = require('esbuild'); + +/** + * The app's built module, wrapped so that its `store.proxy` is the sample + * account of sample-data/.mjs. It bundles the app's built module (before + * the collector prelude), so the sample entry runs the same app build as the + * real entry, minified once more together with the wrapper. + */ +async function buildSample(id, appFile, file, prelude) { + const at = path => JSON.stringify(path); + const result = await esbuild.build({ + stdin: { + contents: [ + `import { view as appView } from ${at(appFile)};`, + `import provider from ${at(resolve(here, 'sample-data', `${id}.mjs`))};`, + `import { sampleView } from ${at(resolve(here, 'sample-data/proxy.mjs'))};`, + 'export const view = sampleView(appView, provider);', + ].join('\n'), + resolveDir: repo, + loader: 'js', + }, + absWorkingDir: repo, + bundle: true, + format: 'esm', + platform: 'browser', + target: 'es2022', + legalComments: 'none', + minify: true, + write: false, + logLevel: 'silent', + plugins: [ + { + // The notion fixture reads its OpenAPI document with node:fs, only + // when the mock proxy asks for `document`; the frame never does. + name: 'no-node-fs', + setup(builder) { + builder.onResolve({ filter: /^node:fs$/ }, () => ({ + path: 'node:fs', + namespace: 'no-node-fs', + })); + builder.onLoad({ filter: /.*/, namespace: 'no-node-fs' }, () => ({ + contents: + 'export function readFileSync() { throw new Error("no file system in the frame"); }', + loader: 'js', + })); + }, + }, + ], + }); + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, prelude + result.outputFiles[0].text); +} + +/** One catalog entry for a built module. */ +function entryFor(source, id, version, bytes, fields) { + const entry = { ...source }; + entry[A + 'localId'] = id; + entry[A + 'shortname'] = id; + for (const [key, value] of Object.entries(fields)) + if (value) entry[A + key] = value; + // A drive app, not a sandbox plugin: it needs no API-plugins host. + delete entry[I + 'requires-api-plugins']; + entry[I + 'version'] = version; + entry[I + 'app-module'] = `apps/${id}/${version}/ui.js`; + entry[I + 'app-module-integrity'] = + 'sha384-' + createHash('sha384').update(bytes).digest('base64'); + + return entry; +} + for (const [id, app] of Object.entries(APPS)) { const version = VERSIONS[id]; const { build } = await import( @@ -91,31 +191,59 @@ for (const [id, app] of Object.entries(APPS)) { ); const file = resolve(out, 'apps', id, version, 'ui.js'); mkdirSync(dirname(file), { recursive: true }); + // The app alone, before the prelude: what a sample entry wraps. await build({ outfile: file }); - if (PRELUDE && app.report) - writeFileSync(file, PRELUDE + readFileSync(file, 'utf8')); + const plain = readFileSync(file, 'utf8'); + const prelude = app.report ? PRELUDE : ''; + if (prelude) writeFileSync(file, prelude + plain); const bytes = readFileSync(file); const source = byShortname(app.base); if (!source) throw new Error(`catalog.json has no entry ${app.base}`); - const entry = { ...source }; - entry[A + 'localId'] = id; - entry[A + 'shortname'] = id; - if (app.name) entry[A + 'name'] = app.name; - if (app.emoji) entry[A + 'emoji'] = app.emoji; - if (app.description) entry[A + 'description'] = app.description; - // A drive app, not a sandbox plugin: it needs no API-plugins host. - delete entry[I + 'requires-api-plugins']; - entry[I + 'version'] = version; - entry[I + 'app-module'] = `apps/${id}/${version}/ui.js`; - entry[I + 'app-module-integrity'] = - 'sha384-' + createHash('sha384').update(bytes).digest('base64'); + const entry = entryFor(source, id, version, bytes, { + name: app.name, + emoji: app.emoji, + description: app.description, + }); entry[I + 'app-row-name'] = app.row[0]; entry[I + 'app-row-name-plural'] = app.row[1]; const at = catalog.indexOf(source); if (app.base === id) catalog[at] = entry; else catalog.splice(at + 1, 0, entry); + + const sample = SAMPLES[id]; + if (!sample) continue; + const sampleId = `${id}-sample`; + const sampleVersion = `${version}-${SAMPLE_VERSION}`; + const sampleFile = resolve(out, 'apps', sampleId, sampleVersion, 'ui.js'); + const appFile = resolve(out, 'apps', id, version, 'plain.js'); + writeFileSync(appFile, plain); + await buildSample(id, appFile, sampleFile, prelude); + rmSync(appFile); + const sampleEntry = entryFor( + entry, + sampleId, + sampleVersion, + readFileSync(sampleFile), + { + name: `${sample.name} (sample data)`, + description: `Try ${sample.name} on invented sample data, without a ${sample.provider} account. For user testing: nothing reaches ${sample.provider}, and its changes stay in this app.`, + }, + ); + catalog.splice(catalog.indexOf(entry) + 1, 0, sampleEntry); +} + +// Sample files testers download during a session (moderator/sessions/*.md +// name them; the page links them): catalog./samples//. +const SAMPLE_FILES = { + money: resolve(repo, 'integrations/money/fixtures/usertest'), +}; +for (const [app, dir] of Object.entries(SAMPLE_FILES)) { + mkdirSync(resolve(out, 'samples', app), { recursive: true }); + for (const name of readdirSync(dir)) + if (/\.(mt940|xml)$/.test(name)) + copyFileSync(resolve(dir, name), resolve(out, 'samples', app, name)); } // Every drive app, Pets included: enabled, and shown without the toggle. diff --git a/usertest/deploy.sh b/usertest/deploy.sh index cf04490f8..bcead1b22 100755 --- a/usertest/deploy.sh +++ b/usertest/deploy.sh @@ -1,6 +1,7 @@ #!/bin/sh -# Copies the built catalog (catalog.mjs), the Caddyfile, server.sh and the -# pinned atomic-server commit (.atomic-server-ref) to the droplet, then +# Copies the built catalog (catalog.mjs: catalog.json, apps/, samples/), the +# Caddyfile, server.sh and the pinned atomic-server commit +# (.atomic-server-ref) to the droplet, then # reloads Caddy. Existing app module versions on the droplet are # kept, so testers who installed an older version can still update from it. # @@ -18,7 +19,7 @@ HERE=$(cd "$(dirname "$0")" && pwd) # COPYFILE_DISABLE and --no-xattrs keep macOS tar from adding ._ files and # extended attributes that GNU tar on the droplet warns about. -(cd "$HERE/out" && COPYFILE_DISABLE=1 tar --no-xattrs -czf - catalog.json apps) | +(cd "$HERE/out" && COPYFILE_DISABLE=1 tar --no-xattrs -czf - catalog.json apps samples) | ssh "$@" "$TARGET" 'mkdir -p /srv/catalog && tar xzf - -C /srv/catalog' # .atomic-server-ref goes along so that server.sh without a SHA runs the pin. (cd "$HERE" && COPYFILE_DISABLE=1 tar --no-xattrs --exclude node_modules -czf - Caddyfile caddy-usertest.conf server.sh collector moderator page -C .. .atomic-server-ref) | diff --git a/usertest/e2e/run.mjs b/usertest/e2e/run.mjs index 8cbabf267..f36af46d4 100644 --- a/usertest/e2e/run.mjs +++ b/usertest/e2e/run.mjs @@ -421,6 +421,39 @@ await check( }, ); +await check( + 'sample files: money links its statements on the catalog host, notion none', + async () => { + const { page, close } = await open(fakeUi, `code=${CODE}&session=money`, { + permissions: ['microphone'], + }); + await page.waitForFunction(() => document.querySelector('#plan option')); + await expectText(page, '#samples h2', EN.samples.heading); + const links = () => + page.locator('#sample-list a').evaluateAll(list => list.map(a => a.href)); + const hrefs = await links(); + const want = [ + 'acme-studio-2026-08.mt940', + 'acme-studio-2026-09.mt940', + 'acme-studio-2026-08.camt053.xml', + ].map(f => `https://catalog.localhost/samples/money/${f}`); + if (JSON.stringify(hrefs) !== JSON.stringify(want)) + throw new Error(`money sample links: ${hrefs}`); + await page.selectOption('#plan', 'notion'); + if (await page.locator('#samples').isVisible()) + throw new Error('notion shows sample files'); + await page.selectOption('#plan', 'money'); + await page.check('#agree'); + await page.click('#type-instead'); + await page.click('#start'); + await expectText(page, '#log p', STUB_LINE, 10000); + // Still there once the session runs: the moderator points at it. + if (!(await page.locator('#samples').isVisible())) + throw new Error('sample files hidden during the session'); + await close(); + }, +); + await check('moderator down (502): network message with retry', async () => { moderatorDown = true; try { diff --git a/usertest/e2e/samples.mjs b/usertest/e2e/samples.mjs new file mode 100644 index 000000000..2fb1743eb --- /dev/null +++ b/usertest/e2e/samples.mjs @@ -0,0 +1,227 @@ +#!/usr/bin/env node +// The sample-data drive apps (../sample-data/, #196) in the pinned +// atomic-server, headless: builds the user-testing catalog the way a deploy +// does (../catalog.mjs), serves it, opens a fresh drive the way the session +// page does (/app/dev-drive plus the catalog URL in localStorage), installs +// each " (sample data)" entry from Integrations, runs its first import +// on the already-connected sample account, checks that an invented record +// shows, and that it still does after a reload of the page (a new frame). +// +// node integrations/tooling/link-atomic-server.mjs # once, as in AGENTS.md +// npm ci --prefix usertest/e2e +// node usertest/e2e/samples.mjs [calendar issue-tracker timesheets notion] +// +// Needs the atomic-server binary that serve.mjs uses +// ($ATOMIC_SERVER_CHECKOUT/target/e2e/atomic-server), or ATOMIC_SERVER_IMAGE. +// Ports 19290-19292 (lane index 19 in lanes.json's port formula, which no +// lane uses). No mock proxy runs: nothing here needs one. +import { mkdtempSync, readFileSync, rmSync } from 'node:fs'; +import { createServer } from 'node:http'; +import { tmpdir } from 'node:os'; +import { dirname, extname, join, normalize, resolve } from 'node:path'; +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import { chromium } from 'playwright'; +import { bringUp, serverCheckout } from '../../integrations/tooling/serve.mjs'; + +// atomic-server's request log is long; serve.mjs passes this through. +process.env.RUST_LOG ??= 'warn'; + +const here = dirname(fileURLToPath(import.meta.url)); +const repo = resolve(here, '../..'); +const LABEL = 'usertest-samples'; +const ports = { atomicServer: 19290, devServer: 19291, mockProxy: 19292 }; +const SERVER = `http://localhost:${ports.atomicServer}`; +const APP_FRAME = 'iframe[title="App"]'; + +/** + * Each sample app: `start` takes it from its first screen (the sample account + * is already connected) through its import; `shows` finds one invented record. + */ +const APPS = { + calendar: { + title: 'Google Calendar (sample data)', + async start(app) { + const choose = app.getByRole('form', { name: 'Choose a calendar' }); + await choose + .getByRole('radio', { name: /Acme Studio/ }) + .waitFor({ timeout: 30_000 }); + await choose + .getByRole('button', { name: 'Import this calendar' }) + .click(); + await app + .locator('.pill') + .filter({ hasText: 'Synced' }) + .waitFor({ timeout: 30_000 }); + }, + async shows(app) { + await app.getByRole('button', { name: 'Agenda', exact: true }).click(); + await app + .getByRole('button', { + name: /^Design review: Bakkerij Zonnig packaging/, + }) + .waitFor({ timeout: 15_000 }); + }, + }, + 'issue-tracker': { + title: 'GitHub issues (sample data)', + async start(app) { + await app + .getByRole('radio', { name: /acme-studio\/website/ }) + .check({ timeout: 30_000 }); + await app + .getByRole('button', { name: 'Import acme-studio/website' }) + .click(); + }, + async shows(app) { + await app + .getByText('Contact form accepts an empty email address') + .first() + .waitFor({ timeout: 30_000 }); + }, + }, + timesheets: { + title: 'Clockify timesheets (sample data)', + async start(app) { + await app + .getByText('Connected as Alex Sample') + .waitFor({ timeout: 30_000 }); + await app.getByRole('button', { name: 'Import entries' }).click(); + }, + async shows(app) { + await app + .getByText('Webshop phase 2') + .first() + .waitFor({ timeout: 30_000 }); + }, + }, + notion: { + title: 'Notion (sample data)', + // Syncs by itself on first open. + async start() {}, + async shows(app) { + await app.getByText('Launch plan').first().waitFor({ timeout: 30_000 }); + }, + }, +}; + +const wanted = process.argv.slice(2).length + ? process.argv.slice(2) + : Object.keys(APPS); +for (const id of wanted) + if (!APPS[id]) + throw new Error(`no sample app ${id}; known: ${Object.keys(APPS)}`); + +// The catalog, built as a deploy builds it. +const out = mkdtempSync(join(tmpdir(), 'usertest-samples-')); +const built = spawnSync( + process.execPath, + [resolve(repo, 'usertest/catalog.mjs'), out], + { + stdio: ['ignore', 'pipe', 'inherit'], + encoding: 'utf8', + }, +); +if (built.status !== 0) throw new Error('catalog.mjs failed'); + +// Served like Caddy serves catalog.: any origin may read it. +const TYPES = { '.json': 'application/json', '.js': 'text/javascript' }; +const catalog = createServer((req, res) => { + const path = normalize( + decodeURIComponent(new URL(req.url, 'http://x').pathname), + ); + try { + const body = readFileSync(join(out, path)); + res.writeHead(200, { + 'content-type': TYPES[extname(path)] ?? 'application/octet-stream', + 'access-control-allow-origin': '*', + }); + res.end(body); + } catch { + res.writeHead(404, { 'access-control-allow-origin': '*' }); + res.end(); + } +}); +await new Promise(done => catalog.listen(0, '127.0.0.1', done)); +const CATALOG_URL = `http://127.0.0.1:${catalog.address().port}/catalog.json`; + +// A fresh store each run, so every app installs into an empty drive. +rmSync(resolve(serverCheckout(), `.lane-store/${LABEL}`), { + recursive: true, + force: true, +}); +const stop = await bringUp({ ports, platforms: [], label: LABEL }); + +const browser = await chromium.launch({ + ...(process.env.CHROMIUM_PATH + ? { executablePath: process.env.CHROMIUM_PATH } + : {}), +}); +let failed = 0; + +try { + for (const id of wanted) { + const spec = APPS[id]; + const context = await browser.newContext(); + const page = await context.newPage(); + const errors = []; + page.on('pageerror', e => errors.push(e.message)); + page.on('console', m => { + if (m.type() === 'error' || m.type() === 'warning') + errors.push(`${m.type()}: ${m.text()}`); + }); + try { + await page.goto(`${SERVER}/app/dev-drive`); + await page.waitForURL(url => !url.pathname.startsWith('/app/dev-drive'), { + timeout: 60_000, + }); + await page.evaluate( + url => localStorage.setItem('plugin-catalog-url', url), + CATALOG_URL, + ); + await page.goto(`${SERVER}/app/integrations`); + const entry = page + .getByRole('region', { name: 'Drive apps' }) + .locator(`[data-catalog-app="${id}-sample"]`); + await entry.waitFor({ timeout: 30_000 }); + await entry + .getByRole('button', { name: `Install ${spec.title}` }) + .click(); + const frame = page.getByRole('main').locator(APP_FRAME); + await frame.waitFor({ timeout: 45_000 }); + const app = page.frameLocator(APP_FRAME); + await app.getByRole('note').filter({ hasText: 'Sample data' }).waitFor(); + await spec.start(app); + await spec.shows(app); + + // Leave the app and come back: a new frame, the same sample account. + const at = page.url(); + await page.reload(); + await page.waitForURL(at); + await page + .getByRole('main') + .locator(APP_FRAME) + .waitFor({ timeout: 45_000 }); + await spec.shows(page.frameLocator(APP_FRAME)); + console.log( + `ok ${spec.title}: imports sample records, keeps them after a reload`, + ); + } catch (error) { + failed++; + console.log(`FAIL ${spec.title}: ${error.message.split('\n')[0]}`); + if (errors.length) + console.log(` page errors: ${errors.join(' | ')}`); + await page.screenshot({ path: join(out, `${id}.png`) }).catch(() => {}); + console.log(` screenshot: ${join(out, `${id}.png`)}`); + } finally { + await context.close(); + } + } +} finally { + await browser.close(); + catalog.close(); + await stop(); +} + +console.log(`\n${wanted.length - failed} passed, ${failed} failed`); +process.exit(failed ? 1 : 0); diff --git a/usertest/moderator/server.mjs b/usertest/moderator/server.mjs index 3c23e8582..48b771463 100644 --- a/usertest/moderator/server.mjs +++ b/usertest/moderator/server.mjs @@ -110,14 +110,27 @@ const PLANS = Object.fromEntries( const DEFAULT_PLAN = 'calendar'; if (!PLANS[DEFAULT_PLAN]) throw new Error(`sessions/${DEFAULT_PLAN}.md is missing`); +/** Files a plan has the tester download from the catalog host's + * `samples/` (#196): the backticked `/` paths on its line that + * starts with `Sample files`. The page links them. */ +function sampleFiles(text) { + const line = text.match(/^Sample files\b.*$/m)?.[0] ?? ''; + + return [...line.matchAll(/`([^`]+)`/g)] + .map(m => m[1]) + .filter(path => /^[a-z0-9-]+\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(path)); +} + /** What the page's "What do you want to test?" menu lists: each plan's - * first line, `# Session plan: `, in the order of their titles. */ + * first line, `# Session plan: <title>`, in the order of their titles, with + * its sample files. */ const PLAN_LIST = Object.entries(PLANS) .map(([id, text]) => { const title = text.match(/^# (?:Session plan: )?(.+)$/m)?.[1]?.trim(); if (!title) throw new Error(`sessions/${id}.md has no # heading`); + const samples = sampleFiles(text); - return { id, title }; + return samples.length ? { id, title, samples } : { id, title }; }) .sort((a, b) => a.title.localeCompare(b.title)); const client = new Anthropic(); diff --git a/usertest/moderator/sessions/README.md b/usertest/moderator/sessions/README.md index 4173b92e3..60769e44a 100644 --- a/usertest/moderator/sessions/README.md +++ b/usertest/moderator/sessions/README.md @@ -24,7 +24,30 @@ prefix; the moderator refuses to start when a plan has none. | `issue-tracker-seeded` | GitHub issues drive app, team tasks in a prepared repository | a GitHub account with write access to a test repository prepared before the session (below) | | `timesheets` | Clockify drive app | a Clockify account with recent entries | | `notion` | Notion drive app | a Notion account with a database | -| `money` | Bank statements (Money) drive app | an MT940 or camt.053 export they are willing to show on screen | +| `money` | Bank statements (Money) drive app | nothing: sample statements on the session page (their own export is optional) | +| `calendar-sample` | Google Calendar drive app, on sample data | nothing | +| `issue-tracker-sample` | GitHub issues drive app, on sample data | nothing | +| `timesheets-sample` | Clockify drive app, on sample data | nothing | +| `notion-sample` | Notion drive app, on sample data | nothing | + +## Sample data (no account needed) + +The `-sample` plans, and `money` by default, need no provider account +(#196). Testers install the app's "(sample data)" entry from the test +catalog: the same app, with its provider answered by invented data in the +app's frame (`../../sample-data/`), already connected. So these sessions +test the app's own screens, not signing in to the provider; that needs the +plan without `-sample` and a real account. Each `-sample` plan says so in +"For the moderator only", so the analysis doesn't report "couldn't connect" +or "not my data" as findings. Use them when the tester has no account, or +when we have no test account to lend. + +A plan whose tester downloads files has a line starting with +`Sample files`, naming them in backticks as `<app>/<file>` paths. The +moderator lists them with the plan (`GET /plans`), and the session page +links them from `https://catalog.<base-domain>/samples/<app>/<file>`, where +`../../catalog.mjs` puts them. The moderator can't speak a URL; the plan +tells it to say "on the session page, under Sample files". ## Preparing `issue-tracker-seeded` @@ -59,9 +82,11 @@ has not been checked against live GitHub. part out. The analysis (`../analyze.mjs`) gets the plan too, and reports a known limit only when the session adds something new about it. - Invented examples only: plans are public. +- On sample data, say so in "For the moderator only": what the tester will + see, and which "failures" (no sign-in, not their data) are expected. The plans come from the laptop sessions of 2026-09-25 onwards (the method is in `.claude/skills/feature-user-testing/SKILL.md`). Those sessions used a local stack with seeded data and the mock proxy. Here testers bring their own accounts, so the tasks refer to "one of your repositories", not to seeded -names. +names, except in the sample-data plans above. diff --git a/usertest/moderator/sessions/calendar-sample.md b/usertest/moderator/sessions/calendar-sample.md new file mode 100644 index 000000000..adcad249a --- /dev/null +++ b/usertest/moderator/sessions/calendar-sample.md @@ -0,0 +1,35 @@ +# Session plan: Google Calendar drive app, with sample data (no account needed) + +The tester needs no Google account. They install "Google Calendar (sample data)" from Integrations, which is the same Calendar app connected to an invented calendar instead of Google: the calendar of a small design studio, Acme Studio, around today. Nothing reaches Google. + +## The session + +The tester already agreed to the recording before this started; don't ask again. Take roughly 15 to 25 minutes, one task at a time. Only move on when a task is done or the tester gives up. + +1. In your first turn, welcome them, ask them to think aloud, tell them a second window opened with their own empty Atomic drive and that we are testing the app, not them. Say that today they play someone at a small design studio, and that the app they will use is connected to a made-up calendar, so nothing they do reaches anyone. End that same turn with task 2. Keep it to four short sentences. +2. Task: "Install Google Calendar with sample data from Integrations, and bring the studio's calendar into Atomic." +3. Task: "What is on the studio's calendar this week? Is there anything all day?" +4. Task: "The design review got a new title. Change it here, and get that change back into the calendar." Afterwards ask whether they would trust this with their real calendar, and why. +5. Task: "Look at the whole month." +6. Task: "Look around what else Atomic can connect to, and try one that interests you." +7. Wrap up: ask what was most confusing, what they liked, and whether they would use this with their own calendar, and for what. Then thank them and say they can close the windows. + +After the thank-you, end your final message with the exact token [END] on its own. Never write [END] earlier. + +## For the moderator only + +This session runs on invented sample data. The app is already connected to a sample account when it opens: there is no Google sign-in and no consent bar. A yellow line above the app says so. Not seeing Google, not being asked to sign in, or the calendar's events not being theirs is expected and not a finding. Every name and place in it is made up. If they install the real "Google Calendar" entry by mistake, steer them back to the one marked "(sample data)". + +The sample calendar, relative to the day the app was installed: "Acme Studio" (theirs) and "Acme team" (read-only). It holds a design review today at 9:30 ("Design review: Bakkerij Zonnig packaging"), "Lotte off" (all day) and a lunch tomorrow, a kick-off the day after, a three-day "Studio offsite, Texel" from six days out, past events of the last week, a weekly "Monday planning" series and one cancelled event. + +What success looks like, never to be said: + +- Task 2: they install "Google Calendar (sample data)" from Integrations, choose the "Acme Studio" calendar and import it. Events appear in the agenda and the week. +- Task 3: the agenda or the week view. The offsite shows on three days. +- Task 4: they edit the title, then review and send it. The change is held until they send it; whether they find that step is the main question. A conflict appears only if the event changed on the other side, which never happens here unless they edit twice from two windows. +- Task 5: the Month hand-off opens the app's table in Atomic's own Calendar view. + +Known limits (only new detail about them is a finding): + +- Recurring events ("Monday planning") are not imported yet; the app says so. +- The sample calendar keeps its changes in the drive, so a reload keeps them, but a fresh install starts over. diff --git a/usertest/moderator/sessions/issue-tracker-sample.md b/usertest/moderator/sessions/issue-tracker-sample.md new file mode 100644 index 000000000..4ac243321 --- /dev/null +++ b/usertest/moderator/sessions/issue-tracker-sample.md @@ -0,0 +1,39 @@ +# Session plan: GitHub issues drive app, with sample data (no account needed) + +The tester needs no GitHub account. They install "GitHub issues (sample data)" from Integrations, which is the same GitHub issues app connected to an invented GitHub account instead of GitHub: the repositories of a small web studio, `acme-studio/website` and `acme-studio/brand-guide`, with a team's issues, labels and comments. Nothing reaches GitHub, so no change can bother anyone. + +## The session + +The tester already agreed to the recording before this started; don't ask again. Take roughly 20 to 30 minutes, one task at a time. Only move on when a task is done or the tester gives up. + +1. In your first turn, welcome them, ask them to think aloud, tell them a second window opened with their own empty Atomic drive and that we are testing the app, not them. Say that today they join a small web studio's team, and that the app they will use is connected to a made-up GitHub, so nothing they do reaches anyone. End that same turn with task 2. Keep it to four short sentences. +2. Task: "Install GitHub issues with sample data from Integrations, and bring the issues of the studio's website into Atomic." +3. Task: "Someone reported that the contact form has a problem. Find that issue and mark it as in progress." +4. Task: "Close an issue that is done, so it is also closed on GitHub." +5. Task: "Leave a comment on one of the issues." +6. Task: "Report a new issue about something small on the website." +7. Task: "Find all issues that are bugs." +8. Ask whether they would trust this with a repository they share with a team, and why. +9. Wrap up: ask what was most confusing, what they liked, and whether they would use this with their own GitHub, and for what. Then thank them and say they can close the windows. + +After the thank-you, end your final message with the exact token [END] on its own. Never write [END] earlier. + +## For the moderator only + +This session runs on invented sample data, the same issues as `issue-tracker-seeded.md` but without a real repository. The app is already connected when it opens: there is no GitHub sign-in and no consent page. A yellow line above the app says so. Not seeing GitHub, or the repositories not being theirs, is expected and not a finding; the sign-in can only be tested with a real account (`issue-tracker.md`). There is no GitHub page to check a change on, and a link to one leads to a page that doesn't exist; ask them instead what they expect GitHub to show now. Their own new issue shows as written by `mock-user`. If they install the real "GitHub issues" entry by mistake, steer them back to the one marked "(sample data)". + +The sample account: `acme-studio/website` (the contact form that accepts an empty email address, footer links to the old blog, and more, with labels such as bug, design and good first issue), `acme-studio/brand-guide` (two issues) and `acme-studio/old-site` (issues turned off, so it can't be chosen). Every person, issue and comment is made up. + +What success looks like, never to be said: + +- Task 2: they install "GitHub issues (sample data)", choose `acme-studio/website` and read what the app will do on GitHub. Then a board appears with Todo, Doing and Done. +- Tasks 3–6: the change appears on the board at once, but it is held as "Waiting to send" until they open "Review and send". The main question of this session is whether they find and understand that step. +- Task 3: moves the issue to Doing, which adds an `atomic:doing` label. +- Task 7: the label filter or the search. + +Known limits (only new detail about them is a finding): + +- Labels and assignees are read-only in the app. +- Jira and Todoist appear in the source picker, disabled. +- Nothing syncs while the app is closed. +- A create whose result is unknown can't be settled in the app (atomic-plugins#156). diff --git a/usertest/moderator/sessions/money.md b/usertest/moderator/sessions/money.md index 3f14b5d8c..21d2f91eb 100644 --- a/usertest/moderator/sessions/money.md +++ b/usertest/moderator/sessions/money.md @@ -1,28 +1,41 @@ # Session plan: Bank statements (Money) drive app -No account is needed, but the tester needs a bank statement export in MT940 or camt.053 format, which many banks offer next to CSV and PDF. It shows real transactions on a recorded screen, so ask whether they are comfortable with that before task 2. If they are not, or have no such file, skip to task 8. +No account is needed. The tester imports bank statement files, and by default uses the sample statements of an invented company, Acme Studio, which the session page links (below). A tester who prefers their own MT940 or camt.053 export may use it instead, but don't suggest it: it puts real transactions on a recorded screen. + +Sample files (linked on the session page): `money/acme-studio-2026-08.mt940`, `money/acme-studio-2026-09.mt940`, `money/acme-studio-2026-08.camt053.xml` ## The session The tester already agreed to the recording before this started; don't ask again. Take roughly 20 to 30 minutes, one task at a time. Only move on when a task is done or the tester gives up. -1. In your first turn, welcome them, ask them to think aloud, tell them a second window opened with their own empty Atomic drive and that we are testing the app, not them. End that same turn by asking whether they have a bank statement export they are comfortable showing on the recorded screen. -2. Task: "Get your bank statement into Atomic." -3. Task: "Import the same file once more, as if by mistake." -4. Task: "Find one payment and see exactly what the bank wrote about it." Don't name the payment. -5. Task: "How much came in and how much went out in that period?" +1. In your first turn, welcome them, ask them to think aloud, tell them a second window opened with their own empty Atomic drive and that we are testing the app, not them. Say that today they play the bookkeeper of a small design studio, and that its bank statements are on the session page, under "Sample files". End that same turn with task 2. +2. Task: "Download the August statement from the session page and get it into Atomic." (It is the file `acme-studio-2026-08.mt940`. Name it only if they ask which one.) +3. Task: "A few weeks later the bank gives you the September statement. Get that one in too." It overlaps the first by two weeks. Afterwards ask whether they trust that nothing is in there twice, and why. +4. Task: "Find the payment to the insurer and see exactly what the bank wrote about it." Don't say more than "the insurer". +5. Task: "How much came in and how much went out in August?" 6. Task: "Give one payment a category, and add a short note to it." 7. Task: "Try importing a file that is not a bank statement, for example a PDF or a photo." 8. Wrap up: ask what was most confusing, what they liked, and whether they would keep their bookkeeping in Atomic and why. Then thank them and say they can close the windows. After the thank-you, end your final message with the exact token [END] on its own. Never write [END] earlier. +If the tester insists on their own export instead: let them, use "your statement" in tasks 2 to 5, replace task 3 with "Import the same file once more, as if by mistake", and keep the rest. + ## For the moderator only +This session runs on invented sample data unless the tester chose their own file. Acme Studio, its account `NL00BANK0000000000` and every counterparty are made up. That the data isn't theirs, or that the account number isn't a real IBAN, is expected and not a finding. You can't say a URL; say "on the session page, under Sample files". + +The sample statements: + +- `acme-studio-2026-08.mt940`: 1 August to 15 September 2026, 31 bookings, opening balance 8,412.50 EUR, closing 11,783.88 EUR. +- `acme-studio-2026-09.mt940`: 1 to 30 September 2026, 25 bookings. The first 10 (1 to 15 September) are the same bookings as at the end of the August file, with the same bank references. Imported after it, only 15 are new. +- `acme-studio-2026-08.camt053.xml`: the same bookings as the August MT940, in camt.053, plus one pending card payment that is not imported. Importing it next to the MT940 gives separate rows (a known limit below), so it is only for a tester who asks about the other format. +- In August: 7,762.75 EUR in, 3,746.74 EUR out. Among the bookings: a refund from Drukkerij Kleur & Co (18.75), a font licence paid in US dollars (USD 49.00, booked as 45.12 EUR, with the rate in the description), and the insurer Verzekeraar Veilig NV, whose direct debit has a seven-line bank description. + What success looks like, never to be said: - Task 2: they install Bank statements from Integrations, run Set up, then import from inside Money through the host's review. Transactions appear, with statements and closing balances. -- Task 3: nothing is imported twice. The review shows the rows as already imported. Watch whether they trust that. +- Task 3: the review shows 15 new and 10 already imported, and nothing is imported twice. Watch whether they trust that. - Task 4: search, then the detail panel with the bank's original description. Amounts are shown exactly, never rounded. - Task 5: money in, out and net per account and currency. Totals are never added across currencies. - Task 6: the "Allow editing" bar comes first, then the category and note save. Note whether the bar makes sense to them. diff --git a/usertest/moderator/sessions/notion-sample.md b/usertest/moderator/sessions/notion-sample.md new file mode 100644 index 000000000..080dac01a --- /dev/null +++ b/usertest/moderator/sessions/notion-sample.md @@ -0,0 +1,37 @@ +# Session plan: Notion drive app, with sample data (no account needed) + +The tester needs no Notion account. They install "Notion (sample data)" from Integrations, which is the same Notion app connected to an invented workspace instead of Notion: a "Roadmap" database with three items and a "Reading list" with two. Nothing reaches Notion. The app only reads. + +## The session + +The tester already agreed to the recording before this started; don't ask again. Take roughly 15 to 20 minutes, one task at a time. Only move on when a task is done or the tester gives up. + +1. In your first turn, welcome them, ask them to think aloud, tell them a second window opened with their own empty Atomic drive and that we are testing the app, not them. Say that the app they will use is connected to a made-up Notion workspace, so nothing they do reaches anyone. End that same turn with task 2. Keep it to four short sentences. +2. Task: "Install Notion with sample data from Integrations, and bring its databases into Atomic." +3. Task: "Which roadmap items are in progress?" +4. Task: "Check whether everything from the roadmap came across. Is anything missing?" +5. Task: "Show only the reading list." +6. Task: "Stop syncing, but keep the data you already have." +7. Wrap up: ask what was most confusing, what they liked, and whether they would use this with their own Notion, and for what. Then thank them and say they can close the windows. + +After the thank-you, end your final message with the exact token [END] on its own. Never write [END] earlier. + +## For the moderator only + +This session runs on invented sample data. The app is already connected when it opens and syncs by itself: there is no Notion sign-in and no page picker. A yellow line above the app says so. Not seeing Notion, or the content not being theirs, is expected and not a finding; the page picker can only be tested with a real account (`notion.md`). "Open in Notion" leads to a page that doesn't exist, so don't ask for it. If they install the real "Notion" entry by mistake, steer them back to the one marked "(sample data)". + +The sample workspace: "Roadmap" with "Launch plan" (In progress), "Write changelog" (Done) and "Retrospective" (Not started); "Reading list" with "Thinking in Systems" (Reading) and "Local-first software" (Finished). One roadmap note has bold text, which is not copied. + +What success looks like, never to be said: + +- Task 2: they install "Notion (sample data)". It syncs on open, and both databases go into one table with a Data source column and chips. +- Task 3: the board (grouped by a status column) or the search. The board is disabled on "All". +- Task 4: "Sync details" lists what was skipped and why (the formatted note). The question is whether they find and understand it. +- Task 5: the "Reading list" chip. +- Task 6: More → Disconnect. The rows stay. + +Known limits (only new detail about them is a finding): + +- Read-only: no changes go back to Notion (atomic-plugins#8). +- A local edit may be overwritten on the next sync (atomic-plugins#97), so don't ask them to edit here. +- The sample workspace doesn't change, so "Sync now" never brings anything new. diff --git a/usertest/moderator/sessions/timesheets-sample.md b/usertest/moderator/sessions/timesheets-sample.md new file mode 100644 index 000000000..818c7d8ae --- /dev/null +++ b/usertest/moderator/sessions/timesheets-sample.md @@ -0,0 +1,37 @@ +# Session plan: Clockify timesheets drive app, with sample data (no account needed) + +The tester needs no Clockify account. They install "Clockify timesheets (sample data)" from Integrations, which is the same Timesheets app connected to an invented Clockify account instead of Clockify: Alex Sample at a small design studio, Acme Studio, with two weeks of time on two client projects. Nothing reaches Clockify. + +## The session + +The tester already agreed to the recording before this started; don't ask again. Take roughly 15 to 25 minutes, one task at a time. Only move on when a task is done or the tester gives up. + +1. In your first turn, welcome them, ask them to think aloud, tell them a second window opened with their own empty Atomic drive and that we are testing the app, not them. Say that today they play Alex, who works at a small design studio, and that the app they will use is connected to a made-up time tracker, so nothing they do reaches anyone. End that same turn with task 2. Keep it to four short sentences. +2. Task: "Install Clockify timesheets with sample data from Integrations, and bring the studio's time from the last week into Atomic." +3. Task: "How many hours did Alex work yesterday, and how many of them were billable?" +4. Task: "What did Alex work on for the webshop this week, and when?" +5. Task: "Now look at the last two weeks." +6. Task: "Stop this app from reading the time tracker, but keep what it already copied." +7. Wrap up: ask what was most confusing, what they liked, and whether they would use this with their own Clockify, and for what. Then thank them and say they can close the windows. + +After the thank-you, end your final message with the exact token [END] on its own. Never write [END] earlier. + +## For the moderator only + +This session runs on invented sample data. The app is already connected when it opens ("Connected as Alex Sample"): there is no Clockify sign-in and no API key step. A yellow line above the app says so. Not being asked for a key, or the time not being theirs, is expected and not a finding; the key step can only be tested with a real account (`timesheets.md`). Every name in it is made up. If they install the real "Clockify" entry by mistake, steer them back to the one marked "(sample data)". + +The sample account, relative to the day the app was installed: workspace "Acme Studio" (and an empty "Personal"), projects "Webshop phase 2" (Fietsenmaker Snel VOF) and "Packaging labels" (Bakkerij Zonnig BV), and 14 entries over the last nine days. Yesterday holds 3.5 hours on the webshop, 1.5 hours of a checkout review and 1.75 hours of label sketches, all billable. Two meetings are not billable. Exact days depend on the weekday of the session. + +What success looks like, never to be said: + +- Task 2: they install "Clockify timesheets (sample data)", choose the "Acme Studio" workspace and a window, and import. The Week grid appears. +- Task 3: the Week grid's day total and the billable split. +- Task 4: the Projects view, or the entry drawer from the grid. +- Task 5: the settings sheet, switching the window to 30 days. +- Task 6: Disconnect in settings. The copied rows stay. + +Known limits (only new detail about them is a finding): + +- Tags, tasks and rates are not copied, and only the user's own entries are. +- After a reload the app can briefly lose its settings. +- A fresh install of the sample app starts over from the same invented entries. diff --git a/usertest/page/app.js b/usertest/page/app.js index c7fbc0756..310b20820 100644 --- a/usertest/page/app.js +++ b/usertest/page/app.js @@ -12,6 +12,8 @@ import { goodEnough, rankVoices } from './voices.js'; const API = '/usertest/api'; const CATALOG_URL = `https://catalog.${location.hostname.replace(/^plugins\./, '')}/catalog.json`; +/** Sample files (moderator/sessions/*.md, "Sample files") live next to it. */ +const SAMPLES_URL = new URL('samples/', CATALOG_URL).href; /** Send a turn this long after the tester stops talking (a question sooner). * Chrome's recognizer adds no punctuation, so questions are recognized by * their words; the moderator answers [WAIT] when nothing needs saying. */ @@ -642,6 +644,9 @@ async function start() { turn(''); } +/** The plans as the moderator listed them, with their sample files. */ +let plans = []; + /** Fills the "What do you want to test?" menu from the moderator's plans. * The link's `session` picks the first choice; a name the moderator doesn't * know stays in the menu, so starting says it is unknown instead of quietly @@ -663,6 +668,7 @@ async function loadPlans() { if (fallback && !list.some(p => p.id === fallback)) list = [{ id: fallback, title: fallback }, ...list]; + plans = list; for (const { id, title } of list) { const option = document.createElement('option'); option.value = id; @@ -671,6 +677,25 @@ async function loadPlans() { } $('plan').value = fallback ?? ''; + showSamples(); +} + +/** Links the chosen plan's sample files, or hides the card. */ +function showSamples() { + const files = plans.find(p => p.id === $('plan').value)?.samples ?? []; + $('sample-list').replaceChildren( + ...files.map(path => { + const item = document.createElement('li'); + const link = document.createElement('a'); + link.href = new URL(path, SAMPLES_URL).href; + link.download = path.split('/').pop(); + link.textContent = path.split('/').pop(); + item.append(link); + + return item; + }), + ); + $('samples').hidden = files.length === 0; } /** Keeps the choice in the address, so a reload keeps it too. */ @@ -913,6 +938,7 @@ $('voice-select').addEventListener('change', chooseVoice); $('voice-try').addEventListener('click', testSpeaker); $('retry').addEventListener('click', () => retryAction?.()); $('plan').addEventListener('change', rememberPlan); +$('plan').addEventListener('change', showSamples); $('start').addEventListener('click', start); $('end').addEventListener('click', () => finish()); // Hands over at once, with whatever was heard so far. diff --git a/usertest/page/i18n.js b/usertest/page/i18n.js index 5b6f56bd8..fe509052c 100644 --- a/usertest/page/i18n.js +++ b/usertest/page/i18n.js @@ -73,6 +73,11 @@ export const TEXT = { </li> </ul>`, plan: 'What do you want to test?', + samples: { + heading: 'Sample files for this session', + intro: + "This session uses invented sample data, so you don't need your own. Download a file when the moderator asks for it.", + }, name: 'Your first name (optional)', sessionLanguage: 'The session is in English. You can switch the language at the top of this page at any time.', @@ -218,6 +223,11 @@ export const TEXT = { </li> </ul>`, plan: 'Wat wil je testen?', + samples: { + heading: 'Voorbeeldbestanden voor deze sessie', + intro: + 'Deze sessie gebruikt verzonnen voorbeeldgegevens, dus je hebt geen eigen gegevens nodig. Download een bestand als de gespreksleider erom vraagt.', + }, name: 'Je voornaam (optioneel)', sessionLanguage: 'De sessie is in het Nederlands. Je kunt de taal bovenaan deze pagina op elk moment wisselen.', diff --git a/usertest/page/index.html b/usertest/page/index.html index 66f61b8b5..72cc51b8a 100644 --- a/usertest/page/index.html +++ b/usertest/page/index.html @@ -117,6 +117,14 @@ <h1 data-text="title"></h1> <select id="plan"></select> </section> + <!-- The chosen plan's sample files (its "Sample files" line), on the + catalog host. Stays visible during the session. --> + <section id="samples" class="card" hidden> + <h2 data-text="samples.heading"></h2> + <p class="muted" data-text="samples.intro"></p> + <ul id="sample-list"></ul> + </section> + <section id="consent" class="card"> <div data-html="consent"></div> <label for="name" data-text="name"></label> diff --git a/usertest/sample-data/README.md b/usertest/sample-data/README.md new file mode 100644 index 000000000..8a498fbf5 --- /dev/null +++ b/usertest/sample-data/README.md @@ -0,0 +1,58 @@ +# Sample data for drive apps + +Moderated sessions where the tester needs no provider account (#196). For +four drive apps, `../catalog.mjs` builds a second catalog entry, "<App> +(sample data)", whose module is the app's own built module wrapped by +`proxy.mjs`: + +| Entry | Provider fixture (the mock proxy's) | Sample account | +| --- | --- | --- | +| `calendar-sample` | `integrations/calendar/fixtures/google-calendar/` | `calendar.mjs`: Acme Studio's calendar around the install day | +| `issue-tracker-sample` | `integrations/issue-tracker/fixtures/github-issues/` (`user-testing` scenario) | `issue-tracker.mjs`: `acme-studio/website`, `brand-guide`, `old-site` | +| `timesheets-sample` | `integrations/timesheets/fixtures/clockify/` | `timesheets.mjs`: Alex Sample, two projects, 14 entries in the last nine days | +| `notion-sample` | `integrations/notion/fixtures/notion/` (`two-sources`) | `notion.mjs`: "Roadmap" and "Reading list", read-only | + +The Money app needs no account at all. Its sample bank statements are in +`integrations/money/fixtures/usertest/` (generated by `generate.mjs` there) +and served at `https://catalog.<base-domain>/samples/money/`. + +## How it works + +- Only `store.proxy` changes. The app runs unchanged, with the host's real + store for everything else: its table, rows, row access and the review + steps are the real ones. `proxy.request` goes to the fixture in the + frame's memory, the same stateful fixture the lanes' e2e tests run behind + the mock proxy. Nothing leaves the frame for the provider. +- The sample account starts connected. So the app goes straight to its + picker or first sync on its first mount, which is the path it takes in the + real host after connecting a new account. `connect` resolves at once and + `disconnect` works. +- The fixture's state survives the frame being remounted (the tester leaves + the app and comes back): the seed, the connected flag and every write the + app sent are kept as JSON in the description of one resource under the + App, named "Sample <provider> account (user testing)", and replayed into a + fresh fixture on load, each with `Date` fixed at its original time. A + fresh install starts over. +- A yellow line above the app's root says the data is invented. +- Every name, place, issue and amount is made up. Keep it that way: these + files and the plans are public. + +## What it can't show + +- Signing in to the provider, the consent bar and the proxy: those need a + real account and the plan without `-sample`. +- Links to the provider's own pages (an event's or issue's page, "Open in + Notion") lead to pages that don't exist. +- Changes made "on the provider's side" during a session: nobody edits the + sample account except the app. + +## Changing it + +Bump `SAMPLE_VERSION` in `../catalog.mjs` whenever this folder or a fixture +it imports changes; the app's own `VERSIONS` bump carries over by itself. +Then: + +```sh +node --test usertest/sample-data/samples.test.mjs +node usertest/e2e/samples.mjs +``` diff --git a/usertest/sample-data/calendar.mjs b/usertest/sample-data/calendar.mjs new file mode 100644 index 000000000..9bacd20f5 --- /dev/null +++ b/usertest/sample-data/calendar.mjs @@ -0,0 +1,173 @@ +/** + * The sample Google Calendar: the mock proxy's google-calendar fixture + * (`integrations/calendar/fixtures/google-calendar/scenario.mjs`), with its + * test events replaced by an invented design studio's fortnight around the + * day the sample account was made. Every name and place is made up. There is + * no `htmlLink`, so nothing offers to open a Google page that doesn't exist. + */ +import { calendarFixture } from '../../integrations/calendar/fixtures/google-calendar/scenario.mjs'; + +const ZONE = 'Europe/Amsterdam'; + +const addDays = (day, n) => + new Date(Date.parse(`${day}T00:00:00Z`) + n * 86_400_000) + .toISOString() + .slice(0, 10); + +/** `+02:00` or `+01:00`: Amsterdam's offset on that day at noon. */ +function offset(day) { + const name = new Intl.DateTimeFormat('en-US', { + timeZone: ZONE, + timeZoneName: 'longOffset', + }) + .formatToParts(new Date(`${day}T12:00:00Z`)) + .find(p => p.type === 'timeZoneName').value; + + return name === 'GMT' ? '+00:00' : name.slice(3); +} + +const at = (day, time) => ({ + dateTime: `${day}T${time}:00${offset(day)}`, + timeZone: ZONE, +}); + +/** [id, title, day offset, start, end, extra]; `start`/`end` null: all day, + * `end` then the number of days. */ +const EVENTS = [ + [ + 'review-zonnig', + 'Design review: Bakkerij Zonnig packaging', + 0, + '09:30', + '10:30', + { + location: 'Studio, room 2', + description: + 'Walk through the three label options and pick one for print.', + }, + ], + [ + 'lunch-ravi', + 'Lunch with Ravi', + 1, + '12:30', + '13:30', + { location: 'Lunchroom Het Plein' }, + ], + ['lotte-off', 'Lotte off', 1, null, 1, {}], + [ + 'kickoff-snel', + 'Kick-off: Fietsenmaker Snel webshop phase 2', + 2, + '10:00', + '11:30', + { + location: 'Fietsenmaker Snel, Utrecht', + description: + 'Scope, planning and who does what. Bring the phase 1 numbers.', + }, + ], + [ + 'call-theater', + 'Call with Theater De Kleine Zaal', + 3, + '15:00', + '15:30', + { + description: 'Programme booklet: deadlines for the winter season.', + }, + ], + ['offsite', 'Studio offsite, Texel', 6, null, 3, { location: 'Texel' }], + ['dentist', 'Dentist', 9, '08:30', '09:00', {}], + [ + 'workshop', + 'Typography workshop', + 13, + '14:00', + '16:00', + { + location: 'Studio', + description: 'Half a day on pairing typefaces. Coffee and cake provided.', + }, + ], + ['invoices', 'Invoice run', -2, '16:00', '17:00', {}], + [ + 'photos', + 'Portfolio photo shoot', + -5, + '11:00', + '12:30', + { location: 'Studio' }, + ], + [ + 'groen-plein', + 'Newsletter check-in, Stichting Groen Plein', + -8, + '10:00', + '10:30', + {}, + ], +]; + +function events(day) { + const list = EVENTS.map(([id, summary, n, start, end, extra]) => { + const d = addDays(day, n); + + return { + id, + summary, + status: 'confirmed', + ...extra, + ...(start === null + ? { start: { date: d }, end: { date: addDays(d, end) } } + : { start: at(d, start), end: at(d, end) }), + }; + }); + // A weekly series and a cancelled event, as a real calendar has: the app + // does not import either yet (a known limit). + const monday = addDays( + day, + (8 - new Date(`${day}T00:00:00Z`).getUTCDay()) % 7, + ); + list.push( + { + id: 'planning', + summary: 'Monday planning', + status: 'confirmed', + recurrence: ['RRULE:FREQ=WEEKLY;BYDAY=MO'], + start: at(monday, '09:00'), + end: at(monday, '09:30'), + }, + { + id: 'planning_1', + summary: 'Monday planning', + status: 'confirmed', + recurringEventId: 'planning', + originalStartTime: at(monday, '09:00'), + start: at(monday, '09:00'), + end: at(monday, '09:30'), + }, + { id: 'moved', status: 'cancelled' }, + ); + + return list; +} + +export default { + platform: 'google-calendar', + name: 'Google Calendar', + seed: () => ({ day: new Date().toISOString().slice(0, 10) }), + create({ day }) { + const fixture = calendarFixture(day); + const [work, team] = fixture.calendars; + work.summary = 'Acme Studio'; + team.summary = 'Acme team'; + fixture.events.splice( + 0, + fixture.events.length, + ...events(day).map((event, i) => ({ ...event, etag: `"s${i + 1}"` })), + ); + + return fixture; + }, +}; diff --git a/usertest/sample-data/issue-tracker.mjs b/usertest/sample-data/issue-tracker.mjs new file mode 100644 index 000000000..b5491cde2 --- /dev/null +++ b/usertest/sample-data/issue-tracker.mjs @@ -0,0 +1,25 @@ +/** + * The sample GitHub account: the mock proxy's github-issues fixture in its + * `user-testing` scenario (`integrations/issue-tracker/fixtures/ + * github-issues/user-testing.mjs`), an invented web studio's repositories + * `acme-studio/website` and `acme-studio/brand-guide`, plus + * `acme-studio/old-site` with issues turned off. Every person, issue and + * comment there is made up. + */ +import { githubTracker } from '../../integrations/issue-tracker/fixtures/github-issues/scenario.mjs'; +import { USER_TESTING_REPOSITORIES } from '../../integrations/issue-tracker/fixtures/github-issues/user-testing.mjs'; + +export default { + platform: 'github-issues', + name: 'GitHub', + seed: () => ({}), + create() { + const fixture = githubTracker({ scenario: 'user-testing' }); + // Seed now, while the clock is the account's creation time, rather than + // on the first read, so a replay gets the same dates. + for (const name of Object.keys(USER_TESTING_REPOSITORIES)) + fixture.snapshot(name); + + return fixture; + }, +}; diff --git a/usertest/sample-data/notion.mjs b/usertest/sample-data/notion.mjs new file mode 100644 index 000000000..08bdad285 --- /dev/null +++ b/usertest/sample-data/notion.mjs @@ -0,0 +1,17 @@ +/** + * The sample Notion workspace: the mock proxy's notion fixture + * (`integrations/notion/fixtures/notion/scenario.mjs`) in its `two-sources` + * scenario, a "Roadmap" and a "Reading list" database, authored from + * Notion's documented response shapes. Read-only, as the fixture is: the + * Notion drive app only reads. + */ +import { notionFixture } from '../../integrations/notion/fixtures/notion/scenario.mjs'; + +export default { + platform: 'notion', + name: 'Notion', + seed: () => ({}), + create: () => notionFixture({ scenario: 'two-sources' }), + // Search and query are POSTs, but nothing here changes the fixture. + isWrite: () => false, +}; diff --git a/usertest/sample-data/proxy.mjs b/usertest/sample-data/proxy.mjs new file mode 100644 index 000000000..6cef8cdf5 --- /dev/null +++ b/usertest/sample-data/proxy.mjs @@ -0,0 +1,281 @@ +/** + * Sample data for drive apps in moderated user testing (#196): the app runs + * unchanged, but its `store.proxy` is answered in the frame by one of the + * mock proxy's stateful provider fixtures (`integrations/<app>/fixtures/`) + * instead of the integration proxy. So a tester needs no Google, GitHub, + * Clockify or Notion account, and nothing reaches a provider. The rest of + * the store (the drive, the table, row access) is the host's, unchanged. + * + * `usertest/catalog.mjs` bundles this around an app's built module as a + * separate catalog entry, "<App> (sample data)"; see README.md. + * + * The sample account starts connected: the app finds the connection on its + * first mount and goes straight to its picker or first sync, the path it + * takes in the real host after connecting a new account (the page comes back + * from the proxy and the frame mounts fresh). `connect` resolves at once, + * like picking an existing connection in the host's consent bar, and + * `disconnect` works as it does at the proxy. + * + * The fixture lives in the frame's memory, and the host remounts the frame + * whenever the tester leaves the app and comes back. To keep the sample + * account's state across that, the provider's seed, whether it is + * connected, and every write the app sent are kept as JSON in the + * description of one resource under the App (the one place a view may + * always write), and replayed into a fresh fixture on load. Fixtures are + * deterministic for the same seed and clock, and each write is replayed + * with `Date` fixed at the time it was first made, so the replay ends in + * the same state, ETags and timestamps included. + */ + +const NAME = 'https://atomicdata.dev/properties/name'; +const DESCRIPTION = 'https://atomicdata.dev/properties/description'; +const PARENT = 'https://atomicdata.dev/properties/parent'; +const CONNECTION = 'sample'; +const FORMAT = 1; + +/** Runs `fn` with `Date` and `Date.now()` fixed at `ms`. Fixtures are + * synchronous, so nothing else runs while the global is swapped. */ +export function atTime(ms, fn) { + const Real = globalThis.Date; + class Fixed extends Real { + constructor(...args) { + if (args.length) super(...args); + else super(ms); + } + static now() { + return ms; + } + } + globalThis.Date = Fixed; + try { + return fn(); + } finally { + globalThis.Date = Real; + } +} + +const lower = headers => + Object.fromEntries( + Object.entries(headers ?? {}).map(([k, v]) => [k.toLowerCase(), String(v)]), + ); + +/** + * A provider fixture, as the mock proxy sees it: `request(method, url, + * body, headers)` with `url` at `/proxy/<platform>/<path>`. + */ +function call(fixture, platform, write, at) { + const url = new URL( + `/proxy/${platform}${write.path}`, + 'https://sample-data.invalid', + ); + for (const [k, v] of Object.entries(write.query ?? {})) + url.searchParams.set(k, v); + const body = + write.body === undefined || write.body === '' + ? undefined + : JSON.parse(write.body); + + return atTime(at, () => + fixture.request(write.method ?? 'GET', url, body, lower(write.headers)), + ); +} + +/** + * The sample account: the fixture, plus its persisted state. + * `provider` is `{ platform, name, seed(), create(seed), isWrite? }`. + */ +export function sampleAccount(store, provider) { + const marker = `Sample ${provider.name} account (user testing)`; + const isWrite = provider.isWrite ?? (method => method !== 'GET'); + let state; + let fixture; + let resource; + let saving = Promise.resolve(); + + const warn = (message, error) => { + console.warn(`[sample data] ${message}`, error); + globalThis.__USERTEST_REPORT__?.({ + level: 'warning', + source: 'sample-data', + app: provider.name, + message: `${message}: ${error?.message ?? error}`, + }); + }; + + const load = async () => { + try { + const app = await store.getApp(); + for (const subject of await store.query({ + property: NAME, + value: marker, + })) { + const found = await store.getResource(subject); + if (found.get(PARENT) !== app) continue; + const saved = JSON.parse(String(found.get(DESCRIPTION))); + if (saved?.format !== FORMAT) continue; + resource = found; + return saved; + } + } catch (error) { + warn('could not read the saved sample account; starting fresh', error); + } + + return { + format: FORMAT, + seed: provider.seed(), + createdAt: Date.now(), + connected: true, + writes: [], + }; + }; + + /** Saves the state, one save at a time; a failure only costs persistence. */ + const persist = () => { + const text = JSON.stringify(state); + saving = saving.then(async () => { + try { + if (!resource) + resource = await store.newResource({ + propVals: { [NAME]: marker, [DESCRIPTION]: text }, + }); + else await resource.set(DESCRIPTION, text).save(); + } catch (error) { + warn('could not save the sample account', error); + } + }); + + return saving; + }; + + const ready = (async () => { + state = await load(); + // A new account's seed is saved at once: Clockify's entries are relative + // to it, so a second mount must not make a new one. + if (!resource) await persist(); + fixture = atTime(state.createdAt, () => provider.create(state.seed)); + for (const write of state.writes) + try { + call(fixture, provider.platform, write, write.at); + } catch (error) { + warn('could not replay a saved write', error); + } + })(); + + const proxy = { + async request(req) { + await ready; + if (req.platform !== provider.platform || req.connectionId !== CONNECTION) + return { status: 404, headers: {}, body: { error: 'No connection' } }; + const write = { + method: req.method ?? 'GET', + path: req.path, + ...(req.query ? { query: req.query } : {}), + ...(req.body !== undefined ? { body: req.body } : {}), + headers: { + ...lower(req.headers), + ...(req.ifMatch ? { 'if-match': req.ifMatch } : {}), + }, + }; + const at = Date.now(); + let response; + try { + response = await call(fixture, provider.platform, write, at); + } catch (error) { + warn( + `the sample ${provider.name} failed on ${write.method} ${write.path}`, + error, + ); + return { + status: 500, + headers: {}, + body: { error: 'Sample data error' }, + }; + } + if ( + isWrite(write.method, write.path) && + response.status >= 200 && + response.status < 300 + ) { + state.writes.push({ ...write, at }); + await persist(); + } + + return { + status: response.status, + headers: lower(response.headers), + body: structuredClone(response.body), + }; + }, + async connections({ platform }) { + await ready; + + return platform === provider.platform && state.connected + ? [{ platform, connectionId: CONNECTION }] + : []; + }, + async connect({ platform }) { + await ready; + if (platform !== provider.platform) return { status: 'cancelled' }; + state.connected = true; + await persist(); + + return { status: 'connected', connectionId: CONNECTION, platform }; + }, + async disconnect({ platform }) { + await ready; + const was = state.connected && platform === provider.platform; + if (was) { + state.connected = false; + await persist(); + } + + return { + status: 'disconnected', + platform, + connectionIds: was ? [CONNECTION] : [], + }; + }, + }; + + return { proxy, ready, state: () => state, fixture: () => fixture }; +} + +/** The host's store with `proxy` answered by the sample account. */ +export function withSampleProxy(store, proxy) { + return new Proxy(store, { + get(target, key) { + if (key === 'proxy') return proxy; + const value = Reflect.get(target, key, target); + + return typeof value === 'function' ? value.bind(target) : value; + }, + has(target, key) { + return key === 'proxy' || Reflect.has(target, key); + }, + }); +} + +/** A line above the app saying the data is invented, outside the app's own + * root so the app cannot clear it. */ +function banner(root, provider) { + const doc = root?.ownerDocument; + if (!doc || !root.parentNode) return; + const note = doc.createElement('p'); + note.setAttribute('role', 'note'); + note.textContent = `Sample data: this app is not connected to a real ${provider.name} account. Everything it shows from ${provider.name} is invented.`; + note.style.cssText = + 'margin:0;padding:6px 12px;font:13px/1.4 system-ui,sans-serif;' + + 'background:var(--t-color-warning,#fff3c4);color:#222;' + + 'border-bottom:1px solid rgba(0,0,0,.15)'; + root.parentNode.insertBefore(note, root); +} + +/** `view({ root, store })` for the app's own `view`, on sample data. */ +export function sampleView(appView, provider) { + return async ({ root, store, ...rest }) => { + banner(root, provider); + const { proxy } = sampleAccount(store, provider); + + return appView({ ...rest, root, store: withSampleProxy(store, proxy) }); + }; +} diff --git a/usertest/sample-data/samples.test.mjs b/usertest/sample-data/samples.test.mjs new file mode 100644 index 000000000..f4e08fb15 --- /dev/null +++ b/usertest/sample-data/samples.test.mjs @@ -0,0 +1,258 @@ +// The sample accounts (proxy.mjs and the four providers) against an +// in-memory stand-in for the host's store: connecting, reading, and writes +// that survive the frame being remounted. No browser, no atomic-server: +// +// node --test usertest/sample-data/samples.test.mjs +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import calendar from './calendar.mjs'; +import issueTracker from './issue-tracker.mjs'; +import notion from './notion.mjs'; +import { sampleAccount, withSampleProxy } from './proxy.mjs'; +import timesheets from './timesheets.mjs'; + +const NAME = 'https://atomicdata.dev/properties/name'; +const DESCRIPTION = 'https://atomicdata.dev/properties/description'; +const PARENT = 'https://atomicdata.dev/properties/parent'; +const APP = 'https://drive.test/app'; + +/** What `view-client.js` offers, as far as proxy.mjs uses it. */ +function hostStore() { + const resources = new Map(); + let next = 0; + const wrap = subject => { + const props = resources.get(subject); + + return { + subject, + props, + get: p => props[p], + set(p, v) { + props[p] = v; + return this; + }, + async save() { + resources.set(subject, { ...props }); + return this; + }, + }; + }; + + return { + resources, + async getApp() { + return APP; + }, + async query({ property, value }) { + return [...resources] + .filter(([, props]) => props[property] === value) + .map(([s]) => s); + }, + async getResource(subject) { + return wrap(subject); + }, + async newResource({ parent, propVals = {} } = {}) { + const subject = `https://drive.test/r${++next}`; + resources.set(subject, { ...propVals, [PARENT]: parent ?? APP }); + return wrap(subject); + }, + }; +} + +const json = text => JSON.stringify(text); + +async function connected(store, provider) { + const { proxy } = sampleAccount(store, provider); + const [first] = await proxy.connections({ platform: provider.platform }); + assert.equal(first?.platform, provider.platform, 'starts connected'); + await proxy.disconnect({ platform: provider.platform }); + assert.deepEqual( + await proxy.connections({ platform: provider.platform }), + [], + 'disconnects', + ); + const result = await proxy.connect({ platform: provider.platform }); + assert.equal(result.status, 'connected'); + assert.deepEqual(await proxy.connections({ platform: provider.platform }), [ + { platform: provider.platform, connectionId: result.connectionId }, + ]); + + return { proxy, connectionId: result.connectionId }; +} + +/** A second mount of the app, as after leaving it and coming back. */ +const remount = (store, provider) => sampleAccount(store, provider).proxy; + +test('calendar: invented events, a PATCH kept across a remount', async () => { + const store = hostStore(); + const { proxy, connectionId } = await connected(store, calendar); + const ask = (p, req) => + p.request({ platform: 'google-calendar', connectionId, ...req }); + + const list = await ask(proxy, { path: '/calendar/v3/users/me/calendarList' }); + assert.deepEqual( + list.body.items.map(c => c.summary), + ['Acme Studio', 'Acme team'], + ); + const day = new Date().toISOString().slice(0, 10); + const query = { + singleEvents: 'true', + showDeleted: 'true', + timeMin: `${day}T00:00:00Z`, + timeMax: '2100-01-01T00:00:00Z', + maxResults: '250', + }; + const titles = []; + let pageToken; + do { + const page = await ask(proxy, { + path: '/calendar/v3/calendars/primary/events', + query: { ...query, ...(pageToken ? { pageToken } : {}) }, + }); + assert.equal(page.status, 200); + titles.push(...page.body.items.map(e => e.summary)); + pageToken = page.body.nextPageToken; + } while (pageToken); + assert.ok(titles.includes('Design review: Bakkerij Zonnig packaging')); + assert.ok(!titles.some(t => /fixture/i.test(t ?? '')), titles.join()); + + const path = '/calendar/v3/calendars/primary/events/review-zonnig'; + const before = await ask(proxy, { path }); + const patched = await ask(proxy, { + method: 'PATCH', + path, + ifMatch: before.headers.etag, + body: json({ summary: 'Design review: labels' }), + }); + assert.equal(patched.status, 200); + + const again = remount(store, calendar); + assert.equal( + (await again.connections({ platform: 'google-calendar' })).length, + 1, + 'still connected', + ); + const after = await ask(again, { path }); + assert.equal(after.body.summary, 'Design review: labels'); + assert.equal(after.headers.etag, patched.headers.etag); + // A stale If-Match is still refused after the replay. + const stale = await ask(again, { + method: 'PATCH', + path, + ifMatch: before.headers.etag, + body: json({ summary: 'x' }), + }); + assert.equal(stale.status, 412); +}); + +test('issue-tracker: acme-studio repositories, writes replayed with their dates', async () => { + const store = hostStore(); + const { proxy, connectionId } = await connected(store, issueTracker); + const ask = (p, req) => + p.request({ platform: 'github-issues', connectionId, ...req }); + + const repos = await ask(proxy, { path: '/user/repos' }); + assert.deepEqual( + repos.body.map(r => r.full_name), + ['acme-studio/website', 'acme-studio/brand-guide', 'acme-studio/old-site'], + ); + const issues = '/repos/acme-studio/website/issues'; + const created = await ask(proxy, { + method: 'POST', + path: issues, + body: json({ title: 'Footer logo is blurry', body: 'On retina screens.' }), + }); + assert.equal(created.status, 201); + const closed = await ask(proxy, { + method: 'PATCH', + path: `${issues}/1`, + body: json({ state: 'closed' }), + }); + assert.equal(closed.status, 200); + const list = await ask(proxy, { path: issues, query: { state: 'all' } }); + + await new Promise(resolve => setTimeout(resolve, 5)); + const again = remount(store, issueTracker); + const replayed = await ask(again, { path: issues, query: { state: 'all' } }); + assert.deepEqual(replayed.body, list.body); +}); + +test('timesheets: an invented fortnight, an edit kept across a remount', async () => { + const store = hostStore(); + const { proxy, connectionId } = await connected(store, timesheets); + const ask = (p, req) => + p.request({ platform: 'clockify', connectionId, ...req }); + + const user = await ask(proxy, { path: '/api/v1/user' }); + assert.equal(user.body.name, 'Alex Sample'); + const ws = user.body.activeWorkspace; + const entries = `/api/v1/workspaces/${ws}/user/${user.body.id}/time-entries`; + const window = { + start: new Date(Date.now() - 14 * 86_400_000).toISOString(), + end: new Date().toISOString(), + }; + const list = await ask(proxy, { path: entries, query: window }); + assert.equal(list.status, 200, JSON.stringify(list.body)); + assert.ok(list.body.length >= 10, `${list.body.length} entries`); + const first = list.body.find(e => e.id === 'sample-01'); + const put = await ask(proxy, { + method: 'PUT', + path: `/api/v1/workspaces/${ws}/time-entries/sample-01`, + body: json({ + start: first.timeInterval.start, + end: first.timeInterval.end, + description: 'Product page layout and copy', + projectId: first.projectId, + billable: true, + }), + }); + assert.equal(put.status, 200, JSON.stringify(put.body)); + + const again = remount(store, timesheets); + const after = await ask(again, { path: entries, query: window }); + assert.equal( + after.body.find(e => e.id === 'sample-01').description, + 'Product page layout and copy', + ); +}); + +test('notion: reads both databases, keeps no write log', async () => { + const store = hostStore(); + const { proxy, connectionId } = await connected(store, notion); + const search = await proxy.request({ + platform: 'notion', + connectionId, + method: 'POST', + path: '/v1/search', + body: json({ filter: { property: 'object', value: 'data_source' } }), + }); + assert.equal(search.status, 200); + assert.equal(search.body.results.length, 2); + const [saved] = [...store.resources.values()]; + assert.deepEqual(JSON.parse(saved[DESCRIPTION]).writes, []); +}); + +test('the state lives in one resource under the app; a wrong connection gets nothing', async () => { + const store = hostStore(); + const { proxy } = await connected(store, calendar); + const res = await proxy.request({ + platform: 'google-calendar', + connectionId: 'someone-else', + path: '/calendar/v3/users/me/calendarList', + }); + assert.equal(res.status, 404); + await proxy.disconnect({ platform: 'google-calendar' }); + assert.equal(store.resources.size, 1); + const [props] = [...store.resources.values()]; + assert.equal(props[PARENT], APP); + assert.equal(props[NAME], 'Sample Google Calendar account (user testing)'); + assert.equal(JSON.parse(props[DESCRIPTION]).connected, false); +}); + +test('withSampleProxy keeps the host store and replaces only proxy', async () => { + const host = { proxy: 'real', getApp: async () => APP }; + const store = withSampleProxy(host, 'sample'); + assert.equal(store.proxy, 'sample'); + assert.equal(await store.getApp(), APP); + assert.ok('proxy' in store); +}); diff --git a/usertest/sample-data/timesheets.mjs b/usertest/sample-data/timesheets.mjs new file mode 100644 index 000000000..080e1f644 --- /dev/null +++ b/usertest/sample-data/timesheets.mjs @@ -0,0 +1,82 @@ +/** + * The sample Clockify account: the mock proxy's clockify fixture + * (`integrations/timesheets/fixtures/clockify/scenario.mjs`), with its test + * names and entries replaced by an invented design studio's last two weeks + * of work, relative to when the sample account was made. Every name is made + * up. The fixture's module constants are renamed in place: this bundle is + * their only user. + */ +import { + ARCHIVED_PROJECT, + DEFAULT_TIME_ZONE, + PROJECT, + PROJECT_2, + USER, + WORKSPACE, + clockifyEntry, + clockifyFixture, + wallClockToInstant, +} from '../../integrations/timesheets/fixtures/clockify/scenario.mjs'; + +Object.assign(WORKSPACE, { name: 'Acme Studio' }); +Object.assign(USER, { name: 'Alex Sample' }); +Object.assign(PROJECT, { + name: 'Webshop phase 2', + clientName: 'Fietsenmaker Snel VOF', +}); +Object.assign(PROJECT_2, { + name: 'Packaging labels', + clientName: 'Bakkerij Zonnig BV', +}); +Object.assign(ARCHIVED_PROJECT, { name: 'Website 2025' }); + +const DAY = 86_400_000; + +/** [days ago, start, end, description, project (2: PROJECT_2), extra] */ +const ENTRIES = [ + [1, '09:00', '12:30', 'Product page layout', 1], + [1, '13:30', '15:00', 'Checkout flow review with client', 1], + [1, '15:15', '17:00', 'Label sketches, round 2', 2], + [2, '09:30', '11:00', 'Weekly planning', 1, { billable: false }], + [2, '11:00', '12:30', 'Colour proofs', 2], + [2, '13:30', '17:30', 'Category page templates', 1], + [3, '09:00', '10:30', 'Label printing quotes', 2], + [3, '10:30', '12:00', 'Image export for product photos', 1], + [6, '09:00', '12:00', 'Wireframes cart and checkout', 1], + [6, '13:00', '16:30', 'Label final artwork', 2], + [7, '10:00', '11:00', 'Call with printer', 2, { billable: false }], + [7, '11:00', '16:00', 'Style guide for the webshop', 1], + [8, '09:00', '12:00', 'Kick-off notes and estimate', 1], + [9, '14:00', '17:00', 'Packaging mood board', 2], +]; + +function entries(now) { + const today = new Date(now).toISOString().slice(0, 10); + const instant = (daysAgo, time) => + wallClockToInstant( + Date.parse(`${today}T${time}:00Z`) - daysAgo * DAY, + DEFAULT_TIME_ZONE, + ); + + return ENTRIES.map(([ago, start, end, description, project, extra], i) => + clockifyEntry( + `sample-${String(i + 1).padStart(2, '0')}`, + description, + instant(ago, start), + instant(ago, end), + { projectId: project === 2 ? PROJECT_2.id : PROJECT.id, ...extra }, + ), + ); +} + +export default { + platform: 'clockify', + name: 'Clockify', + seed: () => ({ now: Date.now() }), + create({ now }) { + const fixture = clockifyFixture(); + fixture.state.entries = entries(now); + + return fixture; + }, +};