feat(nova/react-test-utils): make types for referenceEntries stronger (#169)

sjwilczynski · Stanislaw Wilczynski · web-flow · commit 850b3dd862fb · 2025-08-08T22:14:13.000+02:00
* add stronger reference entries

* Change files

---------

Co-authored-by: Stanislaw Wilczynski &lt;stwilczy@microsoft.com&gt;
diff --git a/change/@nova-examples-91d581e7-0d1e-4e1f-bafe-a9cead450b57.json b/change/@nova-examples-91d581e7-0d1e-4e1f-bafe-a9cead450b57.json
@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "use stronger typing for reference entries",
+  "packageName": "@nova/examples",
+  "email": "stwilczy@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@nova-react-test-utils-8096225d-dd81-4912-929d-ac603e5f8712.json b/change/@nova-react-test-utils-8096225d-dd81-4912-929d-ac603e5f8712.json
@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "add stronger referece entries types",
+  "packageName": "@nova/react-test-utils",
+  "email": "stwilczy@microsoft.com",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/examples/src/apollo/Feedback/Feedback.stories.tsx b/packages/examples/src/apollo/Feedback/Feedback.stories.tsx
@@ -18,7 +18,11 @@ import type { withErrorBoundaryParameters } from "../../testing-utils/decorators
 import { schema } from "../../testing-utils/schema";
 import { defaultNodeResolver } from "../../testing-utils/resolvers";
 
-type NovaParameters = WithNovaEnvironment<FeedbackStoryQuery, TypeMap>;
+type NovaParameters = WithNovaEnvironment<
+  FeedbackStoryQuery,
+  TypeMap,
+  typeof FeedbackComponent
+>;
 
 const meta = {
   component: FeedbackComponent,
diff --git a/packages/examples/src/apollo/Feedback/FeedbackContainer.stories.tsx b/packages/examples/src/apollo/Feedback/FeedbackContainer.stories.tsx
@@ -26,7 +26,11 @@ import { defaultNodeResolver } from "../../testing-utils/resolvers";
 const telemetryEventMock =
   fn<[{ event: FeedbackTelemetryEvent; source: unknown }]>();
 
-type NovaParams = WithNovaEnvironment<UnknownOperation, TypeMap>;
+type NovaParams = WithNovaEnvironment<
+  UnknownOperation,
+  TypeMap,
+  typeof FeedbackContainer
+>;
 
 const meta = {
   component: FeedbackContainer,
diff --git a/packages/examples/src/relay/Feedback/Feedback.stories.tsx b/packages/examples/src/relay/Feedback/Feedback.stories.tsx
@@ -18,7 +18,11 @@ import type { events } from "../../events/events";
 import { fn } from "@storybook/test";
 import { type withErrorBoundaryParameters } from "../../testing-utils/decorators";
 
-type NovaParameters = WithNovaEnvironment<FeedbackStoryQuery, TypeMap>;
+type NovaParameters = WithNovaEnvironment<
+  FeedbackStoryQuery,
+  TypeMap,
+  typeof FeedbackComponent
+>;
 
 const MockPayloadGenerator = new PayloadGenerator(schema);
 
@@ -42,7 +46,7 @@ const meta = {
       `,
       variables: { id: "42" },
       referenceEntries: {
-        feedback: (data) => data?.feedback,
+        feedback: (data) => data.feedback,
       },
     },
   } satisfies NovaParameters,
@@ -65,7 +69,7 @@ export const Primary: Story = {
     const container = within(context.canvasElement);
     // Verify that value from relay resolvers come through
     await container.findByText("Feedback from resolvers: Feedback title");
-  }
+  },
 };
 
 export const Liked: Story = {
diff --git a/packages/examples/src/relay/Feedback/FeedbackContainer.stories.tsx b/packages/examples/src/relay/Feedback/FeedbackContainer.stories.tsx
@@ -22,9 +22,12 @@ import { FeedbackContainer } from "./FeedbackContainer";
 import { type events, type FeedbackTelemetryEvent } from "../../events/events";
 import * as React from "react";
 import { schema } from "../../testing-utils/schema";
-import { displayLabel } from "../resolvers/feedback-resolvers";
 
-type NovaParameters = WithNovaEnvironment<UnknownOperation, TypeMap>;
+type NovaParameters = WithNovaEnvironment<
+  UnknownOperation,
+  TypeMap,
+  typeof FeedbackContainer
+>;
 
 const MockPayloadGenerator = new PayloadGenerator(schema);
 
diff --git a/packages/examples/src/relay/pure-relay/Feedback.stories.tsx b/packages/examples/src/relay/pure-relay/Feedback.stories.tsx
@@ -19,7 +19,11 @@ import * as React from "react";
 import type { events } from "../../events/events";
 import { type withErrorBoundaryParameters } from "../../testing-utils/decorators";
 
-type NovaParameters = WithNovaEnvironment<FeedbackStoryRelayQuery, TypeMap>;
+type NovaParameters = WithNovaEnvironment<
+  FeedbackStoryRelayQuery,
+  TypeMap,
+  typeof FeedbackComponent
+>;
 
 const novaDecorator = getNovaDecorator(schema, {
   getEnvironmentOptions: () => ({
diff --git a/packages/examples/src/relay/pure-relay/SuggestedFriends/SuggestedFriends.stories.tsx b/packages/examples/src/relay/pure-relay/SuggestedFriends/SuggestedFriends.stories.tsx
@@ -11,7 +11,11 @@ import type { TypeMap } from "../../../__generated__/schema.all.interface";
 import { SuggestedFriendsComponent } from "./SuggestedFriends";
 import type { SuggestedFriendsStoryQuery } from "./__generated__/SuggestedFriendsStoryQuery.graphql";
 
-type NovaParameters = WithNovaEnvironment<SuggestedFriendsStoryQuery, TypeMap>;
+type NovaParameters = WithNovaEnvironment<
+  SuggestedFriendsStoryQuery,
+  TypeMap,
+  typeof SuggestedFriendsComponent
+>;
 
 const novaDecorator = getNovaDecorator(schema, {
   getEnvironmentOptions: () => ({
@@ -45,7 +49,7 @@ const meta = {
               },
             },
             {
-              id: "friend-2", 
+              id: "friend-2",
               name: {
                 firstName: "Bob",
                 lastName: "Smith",
@@ -68,15 +72,14 @@ const meta = {
 export default meta;
 type Story = StoryObjWithoutFragmentRefs<typeof meta>;
 
-
 export const WithDefaultFriends: Story = {
   play: async (context) => {
     const container = within(context.canvasElement);
     // Verify that custom names from resolvers come through
     await container.findByText("Alice Johnson");
     await container.findByText("Bob Smith");
     await container.findByText("Carol Williams");
-  }
+  },
 };
 
 export const EmptyState: Story = {
@@ -92,7 +95,7 @@ export const EmptyState: Story = {
   play: async (context) => {
     const container = within(context.canvasElement);
     await container.findByText("No suggested friends available.");
-  }
+  },
 };
 
 export const WithManyFriends: Story = {
@@ -116,9 +119,9 @@ export const WithManyFriends: Story = {
     // Verify we have 10 friends
     await container.findByText("Friend1 TestUser1");
     await container.findByText("Friend10 TestUser10");
-    
+
     // Count the list items
     const listItems = container.getAllByRole("listitem");
     expect(listItems).toHaveLength(10);
-  }
+  },
 };
diff --git a/packages/examples/src/relay/pure-relay/extensions/ServerWithExtension.stories.ts b/packages/examples/src/relay/pure-relay/extensions/ServerWithExtension.stories.ts
@@ -12,7 +12,6 @@ import type { ServerWithExtensionStoryRelayQuery } from "./__generated__/ServerW
 import { within, expect } from "@storybook/test";
 import { schema } from "../../../testing-utils/schema";
 
-
 const novaDecorator = getNovaDecorator(schema, {
   generateFunction: (operation, mockResolvers) => {
     const result = MockPayloadGenerator.generate(
@@ -48,7 +47,11 @@ const meta = {
         }),
       },
     },
-  } satisfies WithNovaEnvironment<ServerWithExtensionStoryRelayQuery, TypeMap>,
+  } satisfies WithNovaEnvironment<
+    ServerWithExtensionStoryRelayQuery,
+    TypeMap,
+    typeof ServerWithExtension
+  >,
 } satisfies Meta<typeof ServerWithExtension>;
 
 export default meta;
diff --git a/packages/examples/src/relay/pure-relay/extensions/ViewDataOnly.stories.ts b/packages/examples/src/relay/pure-relay/extensions/ViewDataOnly.stories.ts
@@ -13,7 +13,11 @@ import { fn, within, expect, waitFor } from "@storybook/test";
 import { type withErrorBoundaryParameters } from "../../../testing-utils/decorators";
 import { ViewDataOnly } from "./ViewDataOnly";
 
-type NovaParameters = WithNovaEnvironment<ViewDataOnlyStoryRelayQuery, TypeMap>;
+type NovaParameters = WithNovaEnvironment<
+  ViewDataOnlyStoryRelayQuery,
+  TypeMap,
+  typeof ViewDataOnly
+>;
 
 const mockOnError = fn<[Error]>();
 
diff --git a/packages/nova-react-test-utils/README.md b/packages/nova-react-test-utils/README.md
@@ -165,7 +165,11 @@ const meta = {
         Feedback: () => sampleFeedback,
       },
     },
-  } satisfies WithNovaEnvironment<FeedbackStoryQuery, TypeMap>,
+  } satisfies WithNovaEnvironment<
+    FeedbackStoryQuery,
+    TypeMap,
+    typeof FeedbackComponent
+  >,
 } satisfies Meta<typeof FeedbackComponent>;
 
 type Story = StoryObjWithoutFragmentRefs<typeof meta>;
@@ -177,7 +181,7 @@ In this example, a wrapping component will execute the `query` with `useLazyLoad
 
 For Relay examples and more real life examples please check the [examples package](../examples/src/).
 
-You can also see that `satisfies WithNovaEnvironment<Operation, TypeMap>` is used to strongly type parameters. The `Operation` is used to make the `referenceEntries` prop strongly typed. If no `query` is defined it can be set to the `UnknownOperation` type exported from the package. The operation types are generated by the GraphQL compiler (either [apollo-react-relay-duct-tape-compiler](https://github.com/microsoft/graphitation/tree/main/packages/apollo-react-relay-duct-tape-compiler) or [relay-compiler](https://github.com/facebook/relay/tree/main/packages/relay-compiler)). The `TypeMap` type gives you strongly typed mock resolvers and can be generated using [typemap-plugin](https://github.com/microsoft/graphitation/tree/main/packages/graphql-codegen-typescript-typemap-plugin) that can be added to graphql codegen config file.
+You can also see that `satisfies WithNovaEnvironment<Operation, TypeMap, typeof Component>` is used to strongly type parameters. The `Operation` is used to validate `referenceEntries` prop parameter and passing `typeof Component` verifies that not only the name of the prop matches but also the returned value. If no `query` is defined `Operation` can be set to the `UnknownOperation` type exported from the package and passing `typeof Component` is not needed. The operation types are generated by the GraphQL compiler (either [apollo-react-relay-duct-tape-compiler](https://github.com/microsoft/graphitation/tree/main/packages/apollo-react-relay-duct-tape-compiler) or [relay-compiler](https://github.com/facebook/relay/tree/main/packages/relay-compiler)). The `TypeMap` type gives you strongly typed mock resolvers and can be generated using [typemap-plugin](https://github.com/microsoft/graphitation/tree/main/packages/graphql-codegen-typescript-typemap-plugin) that can be added to graphql codegen config file.
 
 Additionally, `StoryObjWithoutFragmentRefs` utility type is provided which is just a small wrapper over `StoryObj` type from Storybook that makes sure that `args` don't require you to pass props that are supplied using `referenceEntries` parameter.
 
diff --git a/packages/nova-react-test-utils/src/shared/storybook-nova-decorator-shared.tsx b/packages/nova-react-test-utils/src/shared/storybook-nova-decorator-shared.tsx
@@ -12,6 +12,7 @@ import type { NovaMockEnvironment } from "./nova-mock-environment";
 import { NovaMockEnvironmentProvider } from "./nova-mock-environment";
 import type { ReactRenderer } from "@storybook/react";
 import type { OperationType } from "relay-runtime";
+import type { ValidatedReferenceEntries } from "./types";
 
 type Context = Parameters<Parameters<typeof makeDecorator>[0]["wrapper"]>[1];
 
@@ -32,15 +33,15 @@ export type UnknownOperation = {
 export type WithNovaEnvironment<
   TQuery extends OperationType = UnknownOperation,
   TypeMap extends DefaultMockResolvers = DefaultMockResolvers,
+  TComponent = never,
 > = {
   novaEnvironment: (
     | {
         query: GraphQLTaggedNode | RelayGraphQLTaggedNode;
         variables?: TQuery["variables"];
-        referenceEntries: Record<
-          string,
-          (queryResult: TQuery["response"]) => unknown
-        >;
+        referenceEntries: [TComponent] extends [never]
+          ? Record<string, (queryResult: TQuery["response"]) => unknown>
+          : ValidatedReferenceEntries<TComponent, TQuery>;
       }
     | {
         query?: never;
@@ -107,7 +108,11 @@ export const getDecorator = <E extends NovaMockEnvironment>(
     environment: E,
   ) => void,
 ) => {
-  const WrapperWithEnvironment: React.FC<RendererProps> = ({ params, context, getStory }) => {
+  const WrapperWithEnvironment: React.FC<RendererProps> = ({
+    params,
+    context,
+    getStory,
+  }) => {
     const environment = React.useMemo(() => createEnvironment(params), []);
     if (params.enableQueuedMockResolvers ?? true) {
       initializeGenerator(params, environment);
@@ -127,9 +132,13 @@ export const getDecorator = <E extends NovaMockEnvironment>(
     wrapper: (getStory, context, settings) => {
       const parameters = (settings.parameters ??
         {}) as WithNovaEnvironment["novaEnvironment"];
-      
+
       return (
-        <WrapperWithEnvironment params={parameters} context={context} getStory={getStory} />
+        <WrapperWithEnvironment
+          params={parameters}
+          context={context}
+          getStory={getStory}
+        />
       );
     },
   });
diff --git a/packages/nova-react-test-utils/src/shared/types.d-test.ts b/packages/nova-react-test-utils/src/shared/types.d-test.ts
diff --git a/packages/nova-react-test-utils/src/shared/types.ts b/packages/nova-react-test-utils/src/shared/types.ts
