@seriousgaming/sdk-tools 1.5.0 → 1.6.0

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 (160) hide show
  1. package/dist/bundling/ui-bundler.d.ts +12 -0
  2. package/dist/cli-25RWY5BQ.js +41 -0
  3. package/dist/cli-272KBNJH.js +97 -0
  4. package/dist/cli-2BH7FX27.js +52 -0
  5. package/dist/cli-2GOFEW26.js +81 -0
  6. package/dist/cli-3E3MD5U4.js +21 -0
  7. package/dist/cli-3HE4AVZG.js +115 -0
  8. package/dist/cli-4AKVLEC4.js +1387 -0
  9. package/dist/cli-4BV45LBH.js +126 -0
  10. package/dist/cli-4LKXZQ2B.js +48 -0
  11. package/dist/cli-4UWFQNGF.js +54 -0
  12. package/dist/cli-4YB3ROVR.js +78 -0
  13. package/dist/cli-57RXC3HQ.js +36 -0
  14. package/dist/cli-5JEGTVTG.js +96 -0
  15. package/dist/cli-6AMT3BUO.js +97 -0
  16. package/dist/cli-6RRVEGFB.js +80 -0
  17. package/dist/cli-6WXLXJVX.js +36 -0
  18. package/dist/cli-7OGYADZ3.js +97 -0
  19. package/dist/cli-AK7OIPWY.js +229 -0
  20. package/dist/cli-B4TN6PJP.js +124 -0
  21. package/dist/cli-B6YHEKIJ.js +248 -0
  22. package/dist/cli-BPYMTOUL.js +89 -0
  23. package/dist/cli-BWX5E7TQ.js +23 -0
  24. package/dist/cli-BYJWFFCF.js +37 -0
  25. package/dist/cli-C3NVCKO6.js +43 -0
  26. package/dist/cli-C47GJATR.js +42 -0
  27. package/dist/cli-C5QOJJWX.js +46 -0
  28. package/dist/cli-C6TH5S7K.js +6417 -0
  29. package/dist/cli-DL2CVMRF.js +89 -0
  30. package/dist/cli-DMW2OQIJ.js +76 -0
  31. package/dist/cli-DZW3XD5F.js +143 -0
  32. package/dist/cli-E2NLWIFE.js +1331 -0
  33. package/dist/cli-E33CJRRQ.js +36 -0
  34. package/dist/cli-E6DJIMYD.js +142 -0
  35. package/dist/cli-EEFJKIGL.js +151 -0
  36. package/dist/cli-EVFS55WN.js +185 -0
  37. package/dist/cli-F2D4GGUA.js +549 -0
  38. package/dist/cli-FBTRTIZJ.js +226 -0
  39. package/dist/cli-FWFRKQNE.js +11 -0
  40. package/dist/cli-FYINNRML.js +760 -0
  41. package/dist/cli-G522CPRL.js +88 -0
  42. package/dist/cli-G6KELFSX.js +2847 -0
  43. package/dist/cli-G6UE5NL4.js +90 -0
  44. package/dist/cli-GBFM76BF.js +16 -0
  45. package/dist/cli-GDQ6ILJY.js +101 -0
  46. package/dist/cli-GFBGYFYD.js +50 -0
  47. package/dist/cli-GGPDQNM3.js +35 -0
  48. package/dist/cli-GTSGLN3Z.js +307 -0
  49. package/dist/cli-GUXKQMJ7.js +13641 -0
  50. package/dist/cli-GXD36NF2.js +60 -0
  51. package/dist/cli-HCRTYQQS.js +16 -0
  52. package/dist/cli-HYY64SUD.js +185 -0
  53. package/dist/cli-I355WTAF.js +463 -0
  54. package/dist/cli-IDKYF5XB.js +59 -0
  55. package/dist/cli-ILKCQNM6.js +8 -0
  56. package/dist/cli-IRZ5KB7D.js +36 -0
  57. package/dist/cli-IUS2YCD3.js +31 -0
  58. package/dist/cli-J4DKUUTK.js +138 -0
  59. package/dist/cli-JFU22EJ2.js +187 -0
  60. package/dist/cli-JMZLT65J.js +226 -0
  61. package/dist/cli-JZM7XTNV.js +89 -0
  62. package/dist/cli-K2B6WHKA.js +81 -0
  63. package/dist/cli-KL3756X6.js +126 -0
  64. package/dist/cli-KNOOKGYW.js +88 -0
  65. package/dist/cli-LFGRFIEO.js +226 -0
  66. package/dist/cli-LFM7GJHI.js +0 -0
  67. package/dist/cli-LMDJCHHD.js +304 -0
  68. package/dist/cli-LXYPE3L5.js +99 -0
  69. package/dist/cli-M6BCQRID.js +153 -0
  70. package/dist/cli-MBNMPVDC.js +367 -0
  71. package/dist/cli-MJUYJIEP.js +13 -0
  72. package/dist/cli-MMN4BPO4.js +145 -0
  73. package/dist/cli-MYJGMA6U.js +40 -0
  74. package/dist/cli-N6H6T2E2.js +616 -0
  75. package/dist/cli-O5KP4OVN.js +61 -0
  76. package/dist/cli-O6PWMJTZ.js +25 -0
  77. package/dist/cli-ORIG557O.js +141 -0
  78. package/dist/cli-PFFCNGHI.js +243 -0
  79. package/dist/cli-PNLYX6R6.js +131 -0
  80. package/dist/cli-PQBXVLEU.js +649 -0
  81. package/dist/cli-PTT5RGKO.js +62 -0
  82. package/dist/cli-Q2XJF5AS.js +127 -0
  83. package/dist/cli-QEVDDBNO.js +60 -0
  84. package/dist/cli-QEVE5HUM.js +167 -0
  85. package/dist/cli-QUIJCBYB.js +391 -0
  86. package/dist/cli-QUNIRH7A.js +57 -0
  87. package/dist/cli-QVASWX2A.js +187 -0
  88. package/dist/cli-QWQMPCL6.js +253 -0
  89. package/dist/cli-R4PCG5YX.js +131 -0
  90. package/dist/cli-RA673NGF.js +53 -0
  91. package/dist/cli-RN6IWTL2.js +36 -0
  92. package/dist/cli-ROT3DRKU.js +145 -0
  93. package/dist/cli-RZITKPJX.js +367 -0
  94. package/dist/cli-S5IVGDDD.js +32 -0
  95. package/dist/cli-S5QDONIQ.js +218 -0
  96. package/dist/cli-SIPDUBFL.js +36 -0
  97. package/dist/cli-SMFSZF2G.js +4009 -0
  98. package/dist/cli-SRHBXZCN.js +159 -0
  99. package/dist/cli-TCY5LJ7E.js +88 -0
  100. package/dist/cli-TDSQSCX4.js +131 -0
  101. package/dist/cli-TIDQ4WUE.js +257 -0
  102. package/dist/cli-TLLA6KAP.js +79 -0
  103. package/dist/cli-TPU4TUR6.js +132 -0
  104. package/dist/cli-U2UE7I7J.js +30 -0
  105. package/dist/cli-UELGBQG7.js +101 -0
  106. package/dist/cli-UHSZBKYO.js +97 -0
  107. package/dist/cli-UJ4UCL2Z.js +38 -0
  108. package/dist/cli-UKQYZYFK.js +31 -0
  109. package/dist/cli-UMFFURZ7.js +81 -0
  110. package/dist/cli-UNAJ2OTE.js +15 -0
  111. package/dist/cli-UNJ5X6BU.js +89 -0
  112. package/dist/cli-UTJU4IYG.js +117 -0
  113. package/dist/cli-V4GHRWOV.js +1837 -0
  114. package/dist/cli-VCI3CG36.js +73 -0
  115. package/dist/cli-VCKOC2EV.js +256 -0
  116. package/dist/cli-VL2P354N.js +46 -0
  117. package/dist/cli-WAE26SVW.js +72 -0
  118. package/dist/cli-WOGIAU2E.js +100 -0
  119. package/dist/cli-WU43JT4T.js +52 -0
  120. package/dist/cli-XCO2VQOH.js +122 -0
  121. package/dist/cli-XSVGKI3R.js +39 -0
  122. package/dist/cli-YOTGR3NB.js +82 -0
  123. package/dist/cli-YVVXUD2G.js +197 -0
  124. package/dist/cli-ZISJ36MM.js +89 -0
  125. package/dist/cli-ZTWOE3ZT.js +65 -0
  126. package/dist/cli-ZVSFYDPQ.js +205 -0
  127. package/dist/cli-ZWPYIXNI.js +68 -0
  128. package/dist/cli.js +148 -43093
  129. package/dist/client/build-surfaces.d.ts +33 -0
  130. package/dist/client/dev-server.d.ts +6 -0
  131. package/dist/client/index.d.ts +1 -0
  132. package/dist/client/playwright.d.ts +62 -0
  133. package/dist/client.js +228 -48
  134. package/dist/core/session.d.ts +15 -1
  135. package/dist/dev/console/assets/{index-BVF8exas.js → index-CuMOOH9m.js} +1 -1
  136. package/dist/dev/console/index.html +1 -1
  137. package/dist/dev/shell.d.ts +19 -0
  138. package/dist/dev/surfaces.d.ts +7 -0
  139. package/dist/docs/api/index.md +14 -12
  140. package/dist/docs/api/sdk-tools-client.md +29 -0
  141. package/dist/docs/api/sdk-tools-playwright.md +104 -0
  142. package/dist/docs/changelog.md +19 -0
  143. package/dist/docs/cli-and-dev-server.md +21 -0
  144. package/dist/docs/cli-reference.md +45 -31
  145. package/dist/docs/environment-variables.md +6 -0
  146. package/dist/docs/guides/designing-a-game.md +29 -4
  147. package/dist/docs/guides/starter-game.md +2 -2
  148. package/dist/docs/guides/testing.md +33 -18
  149. package/dist/docs/page-index.md +8 -7
  150. package/dist/docs/recipes/e2e-testing.md +19 -20
  151. package/dist/playwright.js +32232 -0
  152. package/dist/templates/package/claude/rules/workflow-test-engine-or-ui.md +1 -1
  153. package/dist/templates/package/global-setup.ts.template +7 -18
  154. package/dist/templates/package/playwright.config.ts.liquid +8 -11
  155. package/dist/templates/starter-game/playwright.config.ts +8 -11
  156. package/dist/templates/starter-game/testing/e2e/game.spec.ts +1 -1
  157. package/dist/templates/starter-game/testing/e2e/global-setup.ts +7 -18
  158. package/dist/utils/prompt.d.ts +5 -5
  159. package/dist/utils/resource-scan.d.ts +39 -0
  160. package/package.json +7 -3
@@ -18,7 +18,7 @@ Unit and component tests live next to the source they cover: the engine's `engin
18
18
  2. **For logic**, call `Init`, `Run`, a hook, an endpoint or a validator directly with arguments built by `logicArgs` from `@seriousgaming/sdk/testing` (`logicArgs.run({ context, settings: defaultSettings })`), and assert on the returned `capabilities`. For behaviour across several ticks, hooks, validators, endpoints, participants, undo or automatic ticks, use `createTestSession<Context, SharedContext>` in `testing/engine/`: it runs the session the dev server runs, in-process, with offline stubs for `generateText`, `generateSpeech` and `extractText`. The references are `pnpm run --silent sdk docs view guides/testing.md` and `guides/engine-testing.md`.
19
19
  3. **For UI components**, render with `renderUserInterface()` (or `renderSessionUserInterface()`, or `renderSettingsEditor()` for setup and the scenario editor) from `@seriousgaming/sdk/ui/testing`, which supplies every provider the host does. Never `vi.mock` the SDK contexts, and never wire the providers by hand. For a session UI, pass the generated types: `renderSessionUserInterface<SessionData>()`, with fixtures from `createMockTeamState<TeamContext>()` and `createMockSharedState<SharedContext>()`, so a shared capability left on a team fixture fails to compile.
20
20
  4. **Cover the branches.** One test per code path: the happy path plus each failure mode, each option flag, each conditional in `Run`.
21
- 5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`. `pnpm test` is watch mode, so leave it to the user. `pnpm test:e2e` starts an isolated dev server of its own on free ports (`testing/e2e/global-setup.ts`), beside any the user has running.
21
+ 5. **Run the tests**: `pnpm test:run` and `pnpm test:engine`. `pnpm test` is watch mode, so leave it to the user. `pnpm test:e2e` starts an isolated dev server for each Playwright worker on free ports, beside any the user has running, and serves them surfaces built once by `testing/e2e/global-setup.ts`. Import `test` from `@seriousgaming/sdk-tools/playwright` in a spec, not from `@playwright/test`.
22
22
 
23
23
  ## Things that almost always go wrong
24
24
 
@@ -1,21 +1,10 @@
1
- import { dirname } from 'path';
2
-
3
- import type { FullConfig } from '@playwright/test';
4
- import { startDevServer } from '@seriousgaming/sdk-tools/client';
5
-
6
1
  /**
7
- * Start the dev server the browser tests run against, and stop it after them.
2
+ * Build the game's surfaces once, before any test runs, and remove the build
3
+ * after the last.
8
4
  *
9
- * It is the server `sdk dev --isolated --port auto` runs: on free ports, with
10
- * no lock file, and configured from the package alone, so it starts beside
11
- * your own dev server and every run begins from the same place. Running it in
12
- * this process rather than spawning `sdk dev` means stopping it is a call,
13
- * which a run cannot hang on.
5
+ * Every worker's dev server then serves the build as files, so a page loads at
6
+ * once instead of each server compiling the same surfaces through Vite. Set
7
+ * SERIOUSGAMING_BUILT_SURFACES=dist to serve the output of your own
8
+ * `pnpm run sdk build` instead, and build nothing here.
14
9
  */
15
- export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
16
- const server = await startDevServer({
17
- packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
18
- });
19
- process.env.SERIOUSGAMING_DEV_URL = server.url;
20
- return () => server.stop();
21
- }
10
+ export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
@@ -2,18 +2,15 @@ import { defineConfig } from '@playwright/test';
2
2
 
3
3
  export default defineConfig({
4
4
  testDir: './testing/e2e',
5
- // Starts an isolated dev server on free ports, beside any `sdk dev` you
6
- // have running, and stops it when the run ends. It names the server in
7
- // SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
5
+ // Builds the game's surfaces once for the run, so every worker's dev
6
+ // server serves them as files rather than compiling them again.
8
7
  globalSetup: './testing/e2e/global-setup.ts',
9
- // One worker: these tests share a session, so a tick in one is visible to
10
- // the next. Running them in parallel makes each test's starting state
11
- // depend on what another happened to be doing.
12
- workers: 1,
8
+ // Every worker starts its own isolated dev server (the `test` the specs
9
+ // import from `@seriousgaming/sdk-tools/playwright`), so tests in
10
+ // different workers never share a session and can run side by side. Tests
11
+ // that land in the same worker share its server one after another, which
12
+ // is why each spec starts the session again in `beforeEach`.
13
+ fullyParallel: true,
13
14
  // A stray `test.only` passes locally and silently skips the rest on CI.
14
15
  forbidOnly: !!process.env.CI,
15
- use: {
16
- // Read again in each worker, after the global setup has set it.
17
- baseURL: process.env.SERIOUSGAMING_DEV_URL,
18
- },
19
16
  });
@@ -2,18 +2,15 @@ import { defineConfig } from '@playwright/test';
2
2
 
3
3
  export default defineConfig({
4
4
  testDir: './testing/e2e',
5
- // Starts an isolated dev server on free ports, beside any `sdk dev` you
6
- // have running, and stops it when the run ends. It names the server in
7
- // SERIOUSGAMING_DEV_URL, which the SDK's e2e helpers read.
5
+ // Builds the game's surfaces once for the run, so every worker's dev
6
+ // server serves them as files rather than compiling them again.
8
7
  globalSetup: './testing/e2e/global-setup.ts',
9
- // One worker: these tests share a session, so a tick in one is visible to
10
- // the next. Running them in parallel makes each test's starting state
11
- // depend on what another happened to be doing.
12
- workers: 1,
8
+ // Every worker starts its own isolated dev server (the `test` the specs
9
+ // import from `@seriousgaming/sdk-tools/playwright`), so tests in
10
+ // different workers never share a session and can run side by side. Tests
11
+ // that land in the same worker share its server one after another, which
12
+ // is why each spec starts the session again in `beforeEach`.
13
+ fullyParallel: true,
13
14
  // A stray `test.only` passes locally and silently skips the rest on CI.
14
15
  forbidOnly: !!process.env.CI,
15
- use: {
16
- // Read again in each worker, after the global setup has set it.
17
- baseURL: process.env.SERIOUSGAMING_DEV_URL,
18
- },
19
16
  });
@@ -1,4 +1,4 @@
1
- import { expect, test } from '@playwright/test';
1
+ import { expect, test } from '@seriousgaming/sdk-tools/playwright';
2
2
  import { DEV_SERVER, getState, reinitialiseSession, runCommand } from '@seriousgaming/sdk/e2e';
3
3
 
4
4
  test.beforeEach(async () => {
@@ -1,21 +1,10 @@
1
- import { dirname } from 'path';
2
-
3
- import type { FullConfig } from '@playwright/test';
4
- import { startDevServer } from '@seriousgaming/sdk-tools/client';
5
-
6
1
  /**
7
- * Start the dev server the browser tests run against, and stop it after them.
2
+ * Build the game's surfaces once, before any test runs, and remove the build
3
+ * after the last.
8
4
  *
9
- * It is the server `sdk dev --isolated --port auto` runs: on free ports, with
10
- * no lock file, and configured from the package alone, so it starts beside
11
- * your own dev server and every run begins from the same place. Running it in
12
- * this process rather than spawning `sdk dev` means stopping it is a call,
13
- * which a run cannot hang on.
5
+ * Every worker's dev server then serves the build as files, so a page loads at
6
+ * once instead of each server compiling the same surfaces through Vite. Set
7
+ * SERIOUSGAMING_BUILT_SURFACES=dist to serve the output of your own
8
+ * `pnpm run sdk build` instead, and build nothing here.
14
9
  */
15
- export default async function globalSetup(config: FullConfig): Promise<() => Promise<void>> {
16
- const server = await startDevServer({
17
- packagePath: config.configFile ? dirname(config.configFile) : process.cwd(),
18
- });
19
- process.env.SERIOUSGAMING_DEV_URL = server.url;
20
- return () => server.stop();
21
- }
10
+ export { globalSetup as default } from '@seriousgaming/sdk-tools/playwright';
@@ -9,7 +9,7 @@
9
9
  *
10
10
  * Import prompts from here, never from `@inquirer/prompts` directly.
11
11
  */
12
- import * as inquirer from '@inquirer/prompts';
12
+ import type * as Inquirer from '@inquirer/prompts';
13
13
  export declare function canPrompt(): boolean;
14
14
  /** For tests that drive the prompts through a mock: force the gate open or shut. */
15
15
  export declare function setInteractiveOverride(value: boolean | null): void;
@@ -20,11 +20,11 @@ export declare function setAssumeYes(value: boolean): void;
20
20
  * prompt is refused.
21
21
  */
22
22
  export declare function setPromptUsage(value: string | undefined): void;
23
- export declare const input: typeof inquirer.input;
24
- export declare const select: typeof inquirer.select;
25
- export declare const checkbox: typeof inquirer.checkbox;
23
+ export declare const input: typeof Inquirer.input;
24
+ export declare const select: typeof Inquirer.select;
25
+ export declare const checkbox: typeof Inquirer.checkbox;
26
26
  /** A yes/no question that is part of the input, such as 'Add another property?'. */
27
- export declare const confirm: typeof inquirer.confirm;
27
+ export declare const confirm: typeof Inquirer.confirm;
28
28
  /**
29
29
  * 'Are you sure?': a confirmation `--yes` answers. Without a terminal and
30
30
  * without `--yes` it is a usage error, so a script never deletes by accident
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Finding resources on disk.
3
+ *
4
+ * A package declares whatever is on disk (#431) and a resource is named by its
5
+ * directory (#433), so every lookup is a directory scan: there is no list to
6
+ * read and no bundle to open just to learn a name.
7
+ *
8
+ * A resource a game holds exactly one of lives in a fixed slot instead (#435).
9
+ * It has no name, so there is nothing to scan: the slot is the address.
10
+ */
11
+ import { type ResourceMeta, type ResourceType } from '../templating/resource-metadata.js';
12
+ /** Where one resource's bundle sits, relative to the package root. */
13
+ export declare function bundlePath(meta: ResourceMeta, name?: string): string;
14
+ /**
15
+ * Where one resource's files sit inside a built package, relative to `dist/`.
16
+ *
17
+ * The built layout mirrors the authored one (#452): a resource a game holds
18
+ * one of sits at its slot, exactly where its author wrote it. Everything a
19
+ * package may hold several of keeps `<plural>/<identifier>/`, because there
20
+ * the type directory is what stops a hook and a scenario sharing a name from
21
+ * claiming the same folder.
22
+ *
23
+ * A runtime does not need to know which types are singular: manifest version 2
24
+ * carries them under a singular key and the rest under plural keys, so the
25
+ * shape it is already reading says which rule applies.
26
+ */
27
+ export declare function distPath(meta: ResourceMeta, identifier: string): string;
28
+ /**
29
+ * Every resource of one kind on disk, in name order.
30
+ *
31
+ * A slot resource has no name, so this reports the slot when it is filled and
32
+ * nothing when it is not — the callers that fan out over a type still work,
33
+ * and the ones that need the single resource use {@link slotBundleFile}.
34
+ */
35
+ export declare function resourceNames(packagePath: string, meta: ResourceMeta): string[];
36
+ /** Every bundle of one kind on disk, as package-relative paths in name order. */
37
+ export declare function bundlePaths(packagePath: string, meta: ResourceMeta): string[];
38
+ /** The absolute path to one resource's bundle, or undefined when it is absent. */
39
+ export declare function findBundleFile(packagePath: string, type: ResourceType, identifier?: string): string | undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seriousgaming/sdk-tools",
3
- "version": "1.5.0",
3
+ "version": "1.6.0",
4
4
  "description": "SDK tooling for building Serious Gaming games",
5
5
  "homepage": "https://sdk.seriousgaming.com/",
6
6
  "license": "SEE LICENSE IN LICENSE",
@@ -32,6 +32,10 @@
32
32
  "types": "./dist/client/index.d.ts",
33
33
  "default": "./dist/client.js"
34
34
  },
35
+ "./playwright": {
36
+ "types": "./dist/client/playwright.d.ts",
37
+ "default": "./dist/playwright.js"
38
+ },
35
39
  "./host": {
36
40
  "types": "./dist/host/index.d.ts",
37
41
  "default": "./dist/host.js"
@@ -70,7 +74,7 @@
70
74
  "@mui/icons-material": "^9.4.0",
71
75
  "@mui/material": "^9.4.0",
72
76
  "@playwright/test": "^1.64.0",
73
- "@seriousgaming/sdk": "1.5.0",
77
+ "@seriousgaming/sdk": "1.6.0",
74
78
  "@testing-library/jest-dom": "^7.0.1",
75
79
  "@testing-library/react": "^16.3.3",
76
80
  "@types/adm-zip": "^0.5.8",
@@ -100,7 +104,7 @@
100
104
  },
101
105
  "peerDependencies": {
102
106
  "@playwright/test": ">=1.50.0",
103
- "@seriousgaming/sdk": "^1.5.0"
107
+ "@seriousgaming/sdk": "^1.6.0"
104
108
  },
105
109
  "peerDependenciesMeta": {
106
110
  "@playwright/test": {