@xmachines/play-xstate 1.0.0-beta.1

package/test/devtools-integration.spec.ts

@@ -0,0 +1,97 @@
+/**
+ * DevTools integration validation
+ *
+ * Per CONTEXT.md: "XState DevTools connects successfully and displays actor state/transitions"
+ * Per CONTEXT.md: "Snapshot format: Standard XState snapshots (no Play-specific data)"
+ */
+
+import { describe, it as test, expect } from "vitest";
+
+import { setup } from "xstate";
+import { definePlayer } from "../src/define-player.js";
+
+describe("DevTools Integration", () => {
+	test("PlayerActor maintains XState snapshot format", () => {
+		// Create simple machine
+		const machine = setup({
+			types: {
+				context: {} as { count: number },
+				events: {} as { type: "increment" },
+			},
+		}).createMachine({
+			context: { count: 0 },
+			on: {
+				increment: {
+					actions: ({ context }) => {
+						context.count++;
+					},
+				},
+			},
+		});
+
+		// Create player
+		const createPlayer = definePlayer({ machine });
+		const actor = createPlayer({ count: 0 });
+		actor.start();
+
+		// Get snapshot
+		const snapshot = actor.getSnapshot();
+
+		// Verify snapshot has standard XState properties (no Play pollution)
+		expect(snapshot, "Snapshot exists").toBeTruthy();
+		expect("value" in snapshot, "Snapshot has 'value' property").toBeTruthy();
+		expect("context" in snapshot, "Snapshot has 'context' property").toBeTruthy();
+		expect("status" in snapshot, "Snapshot has 'status' property").toBeTruthy();
+
+		// Verify NO Play-specific properties in snapshot
+		expect("_play" in snapshot).toBe(false, "Snapshot should not have '_play' property");
+		expect("_signals" in snapshot).toBe(false, "Snapshot should not have '_signals' property");
+
+		actor.stop();
+	});
+
+	test("PlayerActor signals are accessible separately from snapshots", () => {
+		const machine = setup({
+			types: {
+				context: {} as { userId: string },
+			},
+		}).createMachine({
+			context: { userId: "" },
+			initial: "idle",
+			states: {
+				idle: {
+					meta: {
+						route: "/home",
+						view: { component: "Home" },
+					},
+				},
+			},
+		});
+
+		const catalog = {
+			Home: {
+				schema: {
+					parse: () => ({}),
+					safeParse: () => ({ success: true, data: {} }),
+				} as any, // Mock Zod schema
+				component: () => "Home",
+			},
+		};
+
+		const createPlayer = definePlayer({ machine, catalog });
+		const actor = createPlayer({ userId: "user123" });
+		actor.start();
+
+		// Signals accessible via actor properties (not in snapshot)
+		expect(actor.state, "Actor has state signal").toBeTruthy();
+		expect(actor.currentRoute, "Actor has currentRoute signal").toBeTruthy();
+		expect(actor.currentView, "Actor has currentView signal").toBeTruthy();
+
+		// Signals have get() method
+		expect(typeof actor.state.get).toBe("function");
+		expect(typeof actor.currentRoute.get).toBe("function");
+		expect(typeof actor.currentView.get).toBe("function");
+
+		actor.stop();
+	});
+});

package/test/format-play-route-transitions-query.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from "vitest";
+import { createActor, createMachine, type EventObject } from "xstate";
+import { formatPlayRouteTransitions } from "../src/routing/format-play-route-transitions.js";
+
+describe("formatPlayRouteTransitions - queryParams context assignment", () => {
+	it("should assign routeParams from event.params to context", () => {
+		const machineConfig = {
+			id: "testMachine",
+			initial: "home",
+			context: {
+				routeParams: {},
+				queryParams: {},
+			},
+			states: {
+				home: {
+					id: "home",
+					meta: { route: "/" },
+				},
+				profile: {
+					id: "profile",
+					meta: { route: "/profile/:userId" },
+				},
+			},
+		};
+
+		const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+		const actor = createActor(machine);
+		actor.start();
+
+		// Send play.route event with params
+		actor.send({
+			type: "play.route",
+			to: "#profile",
+			params: { userId: "123" },
+		} as EventObject);
+
+		// Verify routeParams assigned
+		const snapshot = actor.getSnapshot();
+		expect(snapshot.context).toMatchObject({
+			routeParams: { userId: "123" },
+		});
+	});
+
+	it("should assign queryParams from event.query to context", () => {
+		const machineConfig = {
+			id: "testMachine",
+			initial: "home",
+			context: {
+				routeParams: {},
+				queryParams: {},
+			},
+			states: {
+				home: {
+					id: "home",
+					meta: { route: "/" },
+				},
+				settings: {
+					id: "settings",
+					meta: { route: "/settings" },
+				},
+			},
+		};
+
+		const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+		const actor = createActor(machine);
+		actor.start();
+
+		// Send play.route event with query
+		actor.send({
+			type: "play.route",
+			to: "#settings",
+			query: { tab: "security", theme: "dark" },
+		} as EventObject);
+
+		// Verify queryParams assigned
+		const snapshot = actor.getSnapshot();
+		expect(snapshot.context).toMatchObject({
+			queryParams: { tab: "security", theme: "dark" },
+		});
+	});
+
+	it("should assign empty object when query is undefined", () => {
+		const machineConfig = {
+			id: "testMachine",
+			initial: "home",
+			context: {
+				routeParams: {},
+				queryParams: {},
+			},
+			states: {
+				home: {
+					id: "home",
+					meta: { route: "/" },
+				},
+			},
+		};
+
+		const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+		const actor = createActor(machine);
+		actor.start();
+
+		// Send play.route event without query
+		actor.send({
+			type: "play.route",
+			to: "#home",
+		} as EventObject);
+
+		// Verify queryParams is empty object
+		const snapshot = actor.getSnapshot();
+		expect(snapshot.context).toMatchObject({
+			queryParams: {},
+		});
+	});
+
+	it("should assign both routeParams and queryParams when both present", () => {
+		const machineConfig = {
+			id: "testMachine",
+			initial: "home",
+			context: {
+				routeParams: {},
+				queryParams: {},
+			},
+			states: {
+				home: {
+					id: "home",
+					meta: { route: "/" },
+				},
+				profile: {
+					id: "profile",
+					meta: { route: "/profile/:userId" },
+				},
+			},
+		};
+
+		const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+		const actor = createActor(machine);
+		actor.start();
+
+		// Send play.route event with both params and query
+		actor.send({
+			type: "play.route",
+			to: "#profile",
+			params: { userId: "456" },
+			query: { view: "detailed", sort: "date" },
+		} as EventObject);
+
+		// Verify both assigned correctly
+		const snapshot = actor.getSnapshot();
+		expect(snapshot.context).toMatchObject({
+			routeParams: { userId: "456" },
+			queryParams: { view: "detailed", sort: "date" },
+		});
+	});
+
+	it("should preserve context types with queryParams field", () => {
+		// Type-level test: Verify context type includes queryParams
+		type TestContext = {
+			routeParams: Record<string, string>;
+			queryParams: Record<string, string>;
+		};
+
+		const machineConfig = {
+			id: "testMachine",
+			initial: "home",
+			context: {
+				routeParams: {},
+				queryParams: {},
+			} satisfies TestContext,
+			states: {
+				home: {
+					id: "home",
+					meta: { route: "/" },
+				},
+			},
+		};
+
+		const machine = createMachine(formatPlayRouteTransitions(machineConfig));
+		const actor = createActor(machine);
+		actor.start();
+
+		// Verify context includes queryParams
+		const snapshot = actor.getSnapshot();
+
+		expect(snapshot.context).toHaveProperty("queryParams");
+		expect(typeof (snapshot.context as any).queryParams).toBe("object");
+	});
+});