@seriousgaming/sdk-tools 1.5.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/dist/agent/guidance.md +350 -0
  2. package/dist/bundling/ui-bundler.d.ts +12 -0
  3. package/dist/cli-25RWY5BQ.js +41 -0
  4. package/dist/cli-2BH7FX27.js +52 -0
  5. package/dist/cli-2GZYGRVL.js +36 -0
  6. package/dist/cli-2NU2LPEE.js +97 -0
  7. package/dist/cli-3BRC32CP.js +132 -0
  8. package/dist/cli-3D3ZXWOV.js +111 -0
  9. package/dist/cli-3ZKWV3PN.js +96 -0
  10. package/dist/cli-45OCBG53.js +60 -0
  11. package/dist/cli-4LKXZQ2B.js +48 -0
  12. package/dist/cli-4PXNOJQX.js +81 -0
  13. package/dist/cli-4SIWLHQO.js +717 -0
  14. package/dist/cli-4UWFQNGF.js +54 -0
  15. package/dist/cli-4VFZHLDG.js +202 -0
  16. package/dist/cli-4YB3ROVR.js +78 -0
  17. package/dist/cli-5ACDPCXI.js +21 -0
  18. package/dist/cli-5IAW3LIF.js +38 -0
  19. package/dist/cli-5SM367K7.js +30 -0
  20. package/dist/cli-64AB62PM.js +25 -0
  21. package/dist/cli-6K3VQQUS.js +307 -0
  22. package/dist/cli-6QB2VFPY.js +80 -0
  23. package/dist/cli-6SGCYEEC.js +649 -0
  24. package/dist/cli-6UTPHWRQ.js +207 -0
  25. package/dist/cli-6VNKQ3OX.js +391 -0
  26. package/dist/cli-72XDEFU3.js +61 -0
  27. package/dist/cli-7A6MKCUJ.js +463 -0
  28. package/dist/cli-7XLHO2FE.js +226 -0
  29. package/dist/cli-AV2FYC5G.js +225 -0
  30. package/dist/cli-B6YHEKIJ.js +248 -0
  31. package/dist/cli-BJMS3VX3.js +1837 -0
  32. package/dist/cli-BUQI5UU4.js +43 -0
  33. package/dist/cli-BWX5E7TQ.js +23 -0
  34. package/dist/cli-BYCHKSSH.js +1331 -0
  35. package/dist/cli-C3CMJSNL.js +89 -0
  36. package/dist/cli-C47GJATR.js +42 -0
  37. package/dist/cli-C5QOJJWX.js +46 -0
  38. package/dist/cli-C6ZLPK2U.js +124 -0
  39. package/dist/cli-CD5CIJZI.js +72 -0
  40. package/dist/cli-DDJYUKQG.js +36 -0
  41. package/dist/cli-DFBTZEBX.js +167 -0
  42. package/dist/cli-DOXRQ3S5.js +60 -0
  43. package/dist/cli-EVI36HEM.js +79 -0
  44. package/dist/cli-F2D4GGUA.js +549 -0
  45. package/dist/cli-FQRVFGN6.js +0 -0
  46. package/dist/cli-FWFRKQNE.js +11 -0
  47. package/dist/cli-G6CANSPL.js +88 -0
  48. package/dist/cli-GFNDW2DL.js +124 -0
  49. package/dist/cli-HCRTYQQS.js +16 -0
  50. package/dist/cli-HFX3YPUL.js +76 -0
  51. package/dist/cli-HKORECAG.js +53 -0
  52. package/dist/cli-HOE3WLFH.js +73 -0
  53. package/dist/cli-HSIHDN6K.js +187 -0
  54. package/dist/cli-HW53ICZC.js +89 -0
  55. package/dist/cli-IDVUHGKG.js +218 -0
  56. package/dist/cli-IEMKI7J7.js +1387 -0
  57. package/dist/cli-ILFDANBR.js +101 -0
  58. package/dist/cli-ILKCQNM6.js +8 -0
  59. package/dist/cli-IP4RXGHM.js +2847 -0
  60. package/dist/cli-IUS2YCD3.js +31 -0
  61. package/dist/cli-J4DKUUTK.js +138 -0
  62. package/dist/cli-J4UBELKF.js +37 -0
  63. package/dist/cli-JJSWBW4H.js +89 -0
  64. package/dist/cli-JVI24FI6.js +68 -0
  65. package/dist/cli-JZCLIT3O.js +135 -0
  66. package/dist/cli-JZOZOEZM.js +131 -0
  67. package/dist/cli-KGM6RRQW.js +185 -0
  68. package/dist/cli-KGT5L7VZ.js +13641 -0
  69. package/dist/cli-KOGRWFN7.js +89 -0
  70. package/dist/cli-KSGB2ZLK.js +101 -0
  71. package/dist/cli-L7VYSXQK.js +243 -0
  72. package/dist/cli-LK3V4RI5.js +36 -0
  73. package/dist/cli-LQOHATY2.js +126 -0
  74. package/dist/cli-MJUYJIEP.js +13 -0
  75. package/dist/cli-MJV47HKI.js +143 -0
  76. package/dist/cli-MMN4BPO4.js +145 -0
  77. package/dist/cli-MOPSZ3CS.js +88 -0
  78. package/dist/cli-MU5LB43S.js +136 -0
  79. package/dist/cli-MYJGMA6U.js +40 -0
  80. package/dist/cli-N24OHSAN.js +36 -0
  81. package/dist/cli-N45DREM4.js +99 -0
  82. package/dist/cli-N6H6T2E2.js +616 -0
  83. package/dist/cli-NROTDF5Y.js +182 -0
  84. package/dist/cli-O5ABH2WK.js +226 -0
  85. package/dist/cli-OMWC75CC.js +256 -0
  86. package/dist/cli-OXAUOWCN.js +50 -0
  87. package/dist/cli-PGCIHPU7.js +143 -0
  88. package/dist/cli-Q6ZBZYK2.js +35 -0
  89. package/dist/cli-QUNIRH7A.js +57 -0
  90. package/dist/cli-QUSCIUOM.js +142 -0
  91. package/dist/cli-QVASWX2A.js +187 -0
  92. package/dist/cli-QWQMPCL6.js +253 -0
  93. package/dist/cli-QY5NZAR7.js +97 -0
  94. package/dist/cli-R2MUZQE2.js +62 -0
  95. package/dist/cli-RCIWBCXD.js +36 -0
  96. package/dist/cli-RLEGRWFM.js +81 -0
  97. package/dist/cli-RSW6EBBD.js +89 -0
  98. package/dist/cli-RZITKPJX.js +367 -0
  99. package/dist/cli-S5IVGDDD.js +32 -0
  100. package/dist/cli-SRHBXZCN.js +159 -0
  101. package/dist/cli-TDSQSCX4.js +131 -0
  102. package/dist/cli-TIDQ4WUE.js +257 -0
  103. package/dist/cli-TT36JCU5.js +370 -0
  104. package/dist/cli-TTKICM5P.js +100 -0
  105. package/dist/cli-TTMBBEJC.js +131 -0
  106. package/dist/cli-UMEBPAZQ.js +16 -0
  107. package/dist/cli-UNAJ2OTE.js +15 -0
  108. package/dist/cli-UZZFNXRX.js +226 -0
  109. package/dist/cli-VDBW23SS.js +81 -0
  110. package/dist/cli-VL2P354N.js +46 -0
  111. package/dist/cli-VPRRICZA.js +304 -0
  112. package/dist/cli-VQ6HVQW4.js +4010 -0
  113. package/dist/cli-WR3NOY74.js +36 -0
  114. package/dist/cli-WU43JT4T.js +52 -0
  115. package/dist/cli-XAT25PRU.js +117 -0
  116. package/dist/cli-XOTNXEJA.js +124 -0
  117. package/dist/cli-XSLNH5PR.js +6417 -0
  118. package/dist/cli-XSVGKI3R.js +39 -0
  119. package/dist/cli-XZCJIKIV.js +124 -0
  120. package/dist/cli-Y3DDNMPX.js +97 -0
  121. package/dist/cli-Y3O5F4JN.js +90 -0
  122. package/dist/cli-YOTGR3NB.js +82 -0
  123. package/dist/cli-Z56ZIVA6.js +97 -0
  124. package/dist/cli-ZBN5KAIB.js +59 -0
  125. package/dist/cli-ZDOTXEKL.js +31 -0
  126. package/dist/cli-ZDUADFBY.js +88 -0
  127. package/dist/cli-ZJFQ7EEA.js +131 -0
  128. package/dist/cli-ZTWOE3ZT.js +65 -0
  129. package/dist/cli.js +148 -43093
  130. package/dist/client/build-surfaces.d.ts +33 -0
  131. package/dist/client/dev-server.d.ts +6 -0
  132. package/dist/client/index.d.ts +1 -0
  133. package/dist/client/playwright.d.ts +62 -0
  134. package/dist/client.js +228 -48
  135. package/dist/core/session.d.ts +15 -1
  136. package/dist/dev/console/assets/{index-BVF8exas.js → index-CuMOOH9m.js} +1 -1
  137. package/dist/dev/console/index.html +1 -1
  138. package/dist/dev/shell.d.ts +19 -0
  139. package/dist/dev/surfaces.d.ts +7 -0
  140. package/dist/docs/ai-agents.md +1 -1
  141. package/dist/docs/api/index.md +14 -12
  142. package/dist/docs/api/sdk-tools-client.md +29 -0
  143. package/dist/docs/api/sdk-tools-playwright.md +104 -0
  144. package/dist/docs/changelog.md +34 -0
  145. package/dist/docs/cli-and-dev-server.md +21 -0
  146. package/dist/docs/cli-reference.md +45 -31
  147. package/dist/docs/environment-variables.md +6 -0
  148. package/dist/docs/getting-started.md +1 -1
  149. package/dist/docs/guides/designing-a-game.md +29 -4
  150. package/dist/docs/guides/starter-game.md +3 -3
  151. package/dist/docs/guides/testing.md +33 -18
  152. package/dist/docs/guides/upgrading.md +19 -2
  153. package/dist/docs/page-index.md +10 -9
  154. package/dist/docs/recipes/e2e-testing.md +19 -20
  155. package/dist/playwright.js +32232 -0
  156. package/dist/templates/package/CLAUDE.md.template +7 -346
  157. package/dist/templates/package/claude/rules/workflow-create-engine.md +2 -2
  158. package/dist/templates/package/claude/rules/workflow-create-guide.md +2 -2
  159. package/dist/templates/package/claude/rules/workflow-create-user-interface.md +1 -1
  160. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  161. package/dist/templates/package/claude/rules/workflow-update-sdk-version.md +3 -3
  162. package/dist/templates/package/global-setup.ts.template +7 -18
  163. package/dist/templates/package/playwright.config.ts.liquid +8 -11
  164. package/dist/templates/starter-game/playwright.config.ts +8 -11
  165. package/dist/templates/starter-game/testing/e2e/game.spec.ts +1 -1
  166. package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
  167. package/dist/utils/prompt.d.ts +5 -5
  168. package/dist/utils/resource-scan.d.ts +39 -0
  169. package/package.json +7 -3
@@ -2,7 +2,7 @@
2
2
 
3
3
  Test your game's screens in a real browser against an isolated dev server.
4
4
 
5
- **Keywords:** e2e, playwright, browser test, integration test, UI test, iframe, reinitialiseSession, resetSession, runCommand, waitForState, advanceClock, armFault, startDevServer
5
+ **Keywords:** e2e, playwright, browser test, integration test, UI test, iframe, reinitialiseSession, resetSession, runCommand, waitForState, advanceClock, armFault, startDevServer, fullyParallel, workers, buildSurfaces
6
6
 
7
7
  ## Prerequisites
8
8
 
@@ -20,21 +20,10 @@ Test your game's screens in a real browser against an isolated dev server.
20
20
 
21
21
  `--only-shell` installs only the headless shell, which is all a headless run needs. `--headed`, `--debug` and `--ui` open a real browser window, so to use them run the command again without the flag to install full Chromium.
22
22
 
23
- 2. Create `testing/e2e/global-setup.ts`, which starts an isolated dev server in Playwright's own process and stops it when the run ends:
23
+ 2. Create `testing/e2e/global-setup.ts`, which builds your surfaces once for the whole run and removes the build when it ends:
24
24
 
25
25
  ```typescript
26
- import { dirname } from 'path';
27
-
28
- import { startDevServer } from '@seriousgaming/sdk-tools/client';
29
- import type { FullConfig } from '@playwright/test';
30
-
31
- export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
32
- const server = await startDevServer({
33
- packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
34
- });
35
- process.env.SERIOUSGAMING_DEV_URL = server.url;
36
- return () => server.stop();
37
- }
26
+ export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
38
27
  ```
39
28
 
40
29
  3. Create `playwright.config.ts`, and add `"test:e2e": "playwright test"` to `package.json`:
@@ -45,17 +34,16 @@ Test your game's screens in a real browser against an isolated dev server.
45
34
  export default defineConfig({
46
35
  testDir: './testing/e2e',
47
36
  globalSetup: './testing/e2e/global-setup.ts',
48
- workers: 1,
49
- use: { baseURL: process.env.SERIOUSGAMING_DEV_URL },
37
+ fullyParallel: true,
50
38
  });
51
39
  ```
52
40
 
53
- One worker, because the tests share one session. Do not start the server with `webServer` running `pnpm run sdk dev`: Playwright cannot stop it through `pnpm`, and the run hangs.
41
+ Each Playwright worker starts its own isolated dev server, on free ports, and serves the surfaces the global setup built. Tests in different workers never share a session, so they run side by side. Do not start the server with `webServer` running `pnpm run sdk dev`: Playwright cannot stop it through `pnpm`, and the run hangs.
54
42
 
55
43
  4. Start each test from a fresh session, and open a surface with `?bare` so the page holds your game and none of the console:
56
44
 
57
45
  ```typescript
58
- import { expect, test } from '@playwright/test';
46
+ import { expect, test } from '@seriousgaming/sdk-tools/playwright';
59
47
  import { DEV_SERVER, reinitialiseSession } from '@seriousgaming/sdk/e2e';
60
48
 
61
49
  test.beforeEach(async () => {
@@ -70,6 +58,8 @@ Test your game's screens in a real browser against an isolated dev server.
70
58
  });
71
59
  ```
72
60
 
61
+ Import `test` from `@seriousgaming/sdk-tools/playwright`, not `@playwright/test`: it is what starts the worker's server and points `baseURL` and the `/e2e` helpers at it. Tests that land in the same worker share its session one after another, so `reinitialiseSession()` is still needed.
62
+
73
63
  `playerUrl(team, participant?)` is 1-based. `observeUrl`, `waitingRoomUrl`, `setupUrl`, and the other builders are in the [e2e API reference](../api/sdk-e2e.md#dev_server).
74
64
 
75
65
  5. Act through the game's own controls, or as the facilitator with `runCommand`, and read the result with `getState`:
@@ -91,7 +81,15 @@ Test your game's screens in a real browser against an isolated dev server.
91
81
 
92
82
  The faults are `conflict`, `denied`, `llm-failure`, `hook-throw`, `endpoint-timeout`, and `tick-failure`.
93
83
 
94
- 7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, pass `clock: new FakeClock()` to `startDevServer` and move time with `advanceClock(ms)`
84
+ 7. Wait for what happens later with `waitForState`, never a sleep. For automatic ticks, give the spec's servers a fake clock and move time with `advanceClock(ms)`:
85
+
86
+ ```typescript
87
+ import { FakeClock } from '@seriousgaming/sdk-tools/client';
88
+
89
+ test.use({ devServerOptions: { clock: new FakeClock(Date.now()) } });
90
+ ```
91
+
92
+ `devServerOptions` takes what `startDevServer` does (`teams`, `participants`, `scenarioId`, `locale`, `callbacks`), for every server the file's workers start
95
93
 
96
94
  ## Verify
97
95
 
@@ -105,7 +103,8 @@ Every spec passes. Add `--headed` to watch, or `--debug` to step through.
105
103
 
106
104
  | Problem | Solution |
107
105
  | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
108
- | The run hangs after the last test | The server was started with `webServer`; start it with `startDevServer` in a global setup (step 2) |
106
+ | The run hangs after the last test | The server was started with `webServer`; use the `test` from `@seriousgaming/sdk-tools/playwright` instead (step 4) |
107
+ | A change to a surface does not show | The run serves the build its global setup made at the start; run the suite again |
109
108
  | Tests pass alone and fail in a suite | Call `reinitialiseSession()` in `beforeEach`; `resetSession()` keeps teams an earlier test added |
110
109
  | Iframe content is not there yet | Wait on a locator inside the frame (`await frame.locator('#x').waitFor()`) |
111
110
  | The `/e2e` import does not resolve | Set `moduleResolution` to `"bundler"` or `"nodenext"` in `tsconfig.json` |