feat(QwikCityMockProvider): custom loaders & actions mocks

.changeset/seven-poets-repeat.md

@@ -0,0 +1,53 @@
+---
+'@builder.io/qwik-city': patch
+---
+
+feat: allow mocking loaders in QwikCityMockProvider
+
+
+> If you are using `routeLoader$`s in a Qwik Component that you want to test, you can provide a `loaders` prop to mock the data returned by the loaders
+
+```ts title="src/loaders/product.loader.ts"
+import { routeLoader$ } from '@builder.io/qwik-city';
+
+export const useProductData = routeLoader$(async () => {
+  const res = await fetch('https://.../product');
+  const product = (await res.json()) as Product;
+  return product;
+});
+```
+
+```tsx title="src/components/product.tsx"
+import { component$ } from '@builder.io/qwik';
+
+import { useProductData } from '../loaders/product.loader';
+
+export const Footer = component$(() => {
+  const signal = useProductData();
+  return <footer>Product name: {signal.value.product.name}</footer>;
+});
+```
+
+```tsx title="src/components/product.spec.tsx"
+import { createDOM } from '@builder.io/qwik/testing';
+import { test, expect } from 'vitest';
+
+import { Footer } from './product';
+import { useProductData } from '../loaders/product.loader';
+
+test('should render footer with product name', async () => {
+  const { screen, render } = await createDOM();
+  const loadersMock = [
+    {
+      loader: useProductData,
+      data: { product: { name: 'Test Product' } },
+    },
+  ];
+  await render(
+    <QwikCityMockProvider loaders={loadersMock}>
+      <Footer />
+    </QwikCityMockProvider>,
+  );
+  expect(screen.innerHTML).toMatchSnapshot();
+});
+```

packages/docs/src/routes/api/qwik-city/api.json

@@ -530,7 +530,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface QwikCityMockProps \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[goto?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[RouteNavigate](#routenavigate)\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[params?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;string, string&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[url?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface QwikCityMockProps \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[goto?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[RouteNavigate](#routenavigate)\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[loaders?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nArray&lt;{ loader: [Loader](#loader_2)<!-- -->&lt;any&gt;; data: any; }&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[params?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;string, string&gt;\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[url?](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-city/src/runtime/src/qwik-city-component.tsx",
       "mdFile": "qwik-city.qwikcitymockprops.md"
     },

packages/docs/src/routes/api/qwik-city/index.mdx

@@ -1779,6 +1779,21 @@ _(Optional)_
 </td></tr>
 <tr><td>
 
+[loaders?](#)
+
+</td><td>
+
+</td><td>
+
+Array&lt;\{ loader: [Loader](#loader_2)&lt;any&gt;; data: any; }&gt;
+
+</td><td>
+
+_(Optional)_
+
+</td></tr>
+<tr><td>
+
 [params?](#)
 
 </td><td>

packages/docs/src/routes/docs/(qwikcity)/api/index.mdx

@@ -355,7 +355,7 @@ test.each(cases)('should render card with %s %s', async ({text, link}) => {
 });
 ```
 
-> a `goto` prop can be passed to customize the `navigate` behavior during tests
+> A `goto` prop can be passed to customize the `navigate` behavior during tests
 
 ```tsx title="src/components/button.spec.tsx"
 import { $ } from '@builder.io/qwik';
@@ -383,6 +383,53 @@ test('should render the button and navigate', async () => {
 });
 ```
 
+> If you are using `routeLoader$`s in a Qwik Component that you want to test, you can provide a `loaders` prop to mock the data returned by the loaders
+
+```ts title="src/loaders/product.loader.ts"
+import { routeLoader$ } from '@builder.io/qwik-city';
+
+export const useProductData = routeLoader$(async () => {
+  const res = await fetch('https://.../product');
+  const product = (await res.json()) as Product;
+  return product;
+});
+```
+
+```tsx title="src/components/product.tsx"
+import { component$ } from '@builder.io/qwik';
+
+import { useProductData } from '../loaders/product.loader';
+
+export const Footer = component$(() => {
+  const signal = useProductData();
+  return <footer>Product name: {signal.value.product.name}</footer>;
+});
+```
+
+```tsx title="src/components/product.spec.tsx"
+import { createDOM } from '@builder.io/qwik/testing';
+import { test, expect } from 'vitest';
+
+import { Footer } from './product';
+import { useProductData } from '../loaders/product.loader';
+
+test('should render footer with product name', async () => {
+  const { screen, render } = await createDOM();
+  const loadersMock = [
+    {
+      loader: useProductData,
+      data: { product: { name: 'Test Product' } },
+    },
+  ];
+  await render(
+    <QwikCityMockProvider loaders={loadersMock}>
+      <Footer />
+    </QwikCityMockProvider>,
+  );
+  expect(screen.innerHTML).toMatchSnapshot();
+});
+```
+
 ## `<RouterOutlet>`
 
 The `RouterOutlet` component is responsible for rendering the matched route at a given moment, it internally uses the [`useContent()`](/docs/(qwikcity)/api/index.mdx#usecontent) to render the current page, as well as all of the nested layouts.

packages/qwik-city/src/runtime/src/qwik-city-component.tsx

@@ -39,6 +39,8 @@ import type {
   Editable,
   EndpointResponse,
   LoadedRoute,
+  Loader,
+  LoaderInternal,
   MutableRouteLocation,
   PageModule,
   PreventNavigateCallback,
@@ -661,6 +663,10 @@ export interface QwikCityMockProps {
   url?: string;
   params?: Record<string, string>;
   goto?: RouteNavigate;
+  loaders?: Array<{
+    loader: Loader<any>;
+    data: any;
+  }>;
 }
 
 /** @public */
@@ -677,7 +683,13 @@ export const QwikCityMockProvider = component$<QwikCityMockProps>((props) => {
     { deep: false }
   );
 
-  const loaderState = useSignal({});
+  const loaderState = useStore(
+    props.loaders?.reduce(
+      (acc, { loader, data }) => ({ ...acc, [(loader as LoaderInternal).__id]: data }),
+      {} as Record<string, any>
+    ) ?? {},
+    { deep: false }
+  );
   const routeInternal = useSignal<RouteStateInternal>({ type: 'initial', dest: url });
 
   const goto: RouteNavigate =

packages/qwik-city/src/runtime/src/qwik-city.runtime.api.md

@@ -333,6 +333,11 @@ export interface QwikCityMockProps {
     // (undocumented)
     goto?: RouteNavigate;
     // (undocumented)
+    loaders?: Array<{
+        loader: Loader_2<any>;
+        data: any;
+    }>;
+    // (undocumented)
     params?: Record<string, string>;
     // (undocumented)
     url?: string;