@carlonicora/nextjs-jsonapi 1.16.0 → 1.17.0

package/src/testing/factories/createMockResponse.ts

@@ -0,0 +1,93 @@
+import { ApiResponseInterface } from "../../core/interfaces/ApiResponseInterface";
+import { ApiDataInterface } from "../../core/interfaces/ApiDataInterface";
+
+export interface CreateMockResponseOptions {
+  data?: ApiDataInterface | ApiDataInterface[] | null;
+  ok?: boolean;
+  response?: number;
+  error?: string;
+  meta?: Record<string, any>;
+  self?: string;
+  next?: string;
+  prev?: string;
+}
+
+/**
+ * Creates a mock API response for testing.
+ *
+ * @example
+ * ```ts
+ * import { createMockResponse, createMockApiData } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockData = createMockApiData({ type: 'articles', id: '1' });
+ * const response = createMockResponse({ data: mockData, ok: true });
+ * ```
+ *
+ * @example With pagination
+ * ```ts
+ * const response = createMockResponse({
+ *   data: [mockData],
+ *   ok: true,
+ *   next: '/articles?page=2',
+ *   prev: '/articles?page=0',
+ * });
+ * ```
+ */
+export function createMockResponse(options: CreateMockResponseOptions = {}): ApiResponseInterface {
+  const {
+    data = null,
+    ok = true,
+    response = ok ? 200 : 500,
+    error = ok ? "" : "Error",
+    meta,
+    self,
+    next,
+    prev,
+  } = options;
+
+  const mockResponse: ApiResponseInterface = {
+    ok,
+    response,
+    data: data as ApiDataInterface | ApiDataInterface[],
+    error,
+    meta,
+    self,
+    next,
+    prev,
+  };
+
+  // Add pagination methods if next/prev provided
+  if (next) {
+    mockResponse.nextPage = async () =>
+      createMockResponse({ ...options, next: undefined, prev: self });
+  }
+
+  if (prev) {
+    mockResponse.prevPage = async () =>
+      createMockResponse({ ...options, prev: undefined, next: self });
+  }
+
+  return mockResponse;
+}
+
+/**
+ * Creates a mock error response for testing error scenarios.
+ *
+ * @example
+ * ```ts
+ * import { createMockErrorResponse } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const errorResponse = createMockErrorResponse(404, 'Not Found');
+ * ```
+ */
+export function createMockErrorResponse(
+  statusCode: number,
+  errorMessage: string
+): ApiResponseInterface {
+  return createMockResponse({
+    ok: false,
+    response: statusCode,
+    error: errorMessage,
+    data: null,
+  });
+}

package/src/testing/factories/createMockService.ts

@@ -0,0 +1,79 @@
+import { vi, type Mock } from "vitest";
+import { ApiResponseInterface } from "../../core/interfaces/ApiResponseInterface";
+import { createMockResponse } from "./createMockResponse";
+
+export type MockApiMethod = Mock<(...args: any[]) => Promise<ApiResponseInterface>>;
+
+export interface MockService {
+  get: MockApiMethod;
+  post: MockApiMethod;
+  put: MockApiMethod;
+  patch: MockApiMethod;
+  delete: MockApiMethod;
+}
+
+export interface CreateMockServiceOptions {
+  defaultResponse?: ApiResponseInterface;
+}
+
+/**
+ * Creates a mock service with Vitest mock functions for all HTTP methods.
+ *
+ * @example
+ * ```ts
+ * import { createMockService, createMockResponse } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const mockService = createMockService();
+ * mockService.get.mockResolvedValue(createMockResponse({ data: mockData }));
+ *
+ * // Use in test
+ * expect(mockService.get).toHaveBeenCalled();
+ * ```
+ *
+ * @example With default response
+ * ```ts
+ * const mockService = createMockService({
+ *   defaultResponse: createMockResponse({ ok: true, data: [] }),
+ * });
+ * ```
+ */
+export function createMockService(options: CreateMockServiceOptions = {}): MockService {
+  const defaultResponse = options.defaultResponse ?? createMockResponse({ ok: true });
+
+  return {
+    get: vi.fn().mockResolvedValue(defaultResponse),
+    post: vi.fn().mockResolvedValue(defaultResponse),
+    put: vi.fn().mockResolvedValue(defaultResponse),
+    patch: vi.fn().mockResolvedValue(defaultResponse),
+    delete: vi.fn().mockResolvedValue(defaultResponse),
+  };
+}
+
+/**
+ * Creates a mock service that returns errors for all methods.
+ *
+ * @example
+ * ```ts
+ * import { createMockErrorService } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const errorService = createMockErrorService(500, 'Internal Server Error');
+ * ```
+ */
+export function createMockErrorService(
+  statusCode: number = 500,
+  errorMessage: string = "Error"
+): MockService {
+  const errorResponse = createMockResponse({
+    ok: false,
+    response: statusCode,
+    error: errorMessage,
+  });
+
+  return {
+    get: vi.fn().mockResolvedValue(errorResponse),
+    post: vi.fn().mockResolvedValue(errorResponse),
+    put: vi.fn().mockResolvedValue(errorResponse),
+    patch: vi.fn().mockResolvedValue(errorResponse),
+    delete: vi.fn().mockResolvedValue(errorResponse),
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Test utilities for @carlonicora/nextjs-jsonapi
+ *
+ * Import from '@carlonicora/nextjs-jsonapi/testing'
+ *
+ * @example
+ * ```ts
+ * import {
+ *   MockJsonApiProvider,
+ *   renderWithProviders,
+ *   createMockApiData,
+ *   createMockResponse,
+ *   createMockModule,
+ *   createMockService,
+ *   jsonApiMatchers,
+ *   extendExpectWithJsonApiMatchers,
+ * } from '@carlonicora/nextjs-jsonapi/testing';
+ * ```
+ */
+
+// Providers
+export {
+  MockJsonApiProvider,
+  defaultMockConfig,
+  type MockJsonApiProviderProps,
+} from "./providers/MockJsonApiProvider";
+
+// Factories
+export {
+  createMockModule,
+  type CreateMockModuleOptions,
+} from "./factories/createMockModule";
+
+export {
+  createMockResponse,
+  createMockErrorResponse,
+  type CreateMockResponseOptions,
+} from "./factories/createMockResponse";
+
+export {
+  createMockService,
+  createMockErrorService,
+  type MockService,
+  type MockApiMethod,
+  type CreateMockServiceOptions,
+} from "./factories/createMockService";
+
+export {
+  createMockApiData,
+  createMockApiDataList,
+  type CreateMockApiDataOptions,
+} from "./factories/createMockApiData";
+
+// Matchers
+export {
+  jsonApiMatchers,
+  extendExpectWithJsonApiMatchers,
+} from "./matchers/jsonApiMatchers";
+
+// Utilities
+export {
+  renderWithProviders,
+  render,
+  screen,
+  waitFor,
+  fireEvent,
+  within,
+  userEvent,
+  type RenderWithProvidersOptions,
+} from "./utils/renderWithProviders";

package/src/testing/matchers/jsonApiMatchers.ts

@@ -0,0 +1,174 @@
+import { expect } from "vitest";
+
+interface JsonApiResponse {
+  data?: {
+    type?: string;
+    id?: string;
+    attributes?: Record<string, any>;
+    relationships?: Record<string, any>;
+  } | Array<{
+    type?: string;
+    id?: string;
+    attributes?: Record<string, any>;
+    relationships?: Record<string, any>;
+  }>;
+}
+
+/**
+ * Custom Vitest matchers for JSON:API assertions.
+ *
+ * @example
+ * ```ts
+ * import { jsonApiMatchers } from '@carlonicora/nextjs-jsonapi/testing';
+ * import { expect } from 'vitest';
+ *
+ * expect.extend(jsonApiMatchers);
+ *
+ * // Then use in tests:
+ * expect(response).toBeValidJsonApi();
+ * expect(response).toHaveJsonApiType('articles');
+ * expect(response).toHaveJsonApiAttribute('title', 'My Article');
+ * expect(response).toHaveJsonApiRelationship('author');
+ * ```
+ */
+export const jsonApiMatchers = {
+  /**
+   * Asserts that the response has a valid JSON:API structure with type and id.
+   */
+  toBeValidJsonApi(received: JsonApiResponse) {
+    const data = Array.isArray(received?.data) ? received.data[0] : received?.data;
+    const hasType = typeof data?.type === "string" && data.type.length > 0;
+    const hasId = typeof data?.id === "string" && data.id.length > 0;
+    const isValid = hasType && hasId;
+
+    return {
+      pass: isValid,
+      message: () =>
+        isValid
+          ? `Expected response not to be valid JSON:API, but it has type "${data?.type}" and id "${data?.id}"`
+          : `Expected response to be valid JSON:API with type and id, but got type: ${JSON.stringify(data?.type)}, id: ${JSON.stringify(data?.id)}`,
+    };
+  },
+
+  /**
+   * Asserts that the response data has the expected JSON:API type.
+   */
+  toHaveJsonApiType(received: JsonApiResponse, expectedType: string) {
+    const data = Array.isArray(received?.data) ? received.data[0] : received?.data;
+    const actualType = data?.type;
+    const pass = actualType === expectedType;
+
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `Expected response not to have JSON:API type "${expectedType}"`
+          : `Expected response to have JSON:API type "${expectedType}", but got "${actualType}"`,
+    };
+  },
+
+  /**
+   * Asserts that the response data has an attribute with the expected value.
+   */
+  toHaveJsonApiAttribute(
+    received: JsonApiResponse,
+    attributeName: string,
+    expectedValue?: any
+  ) {
+    const data = Array.isArray(received?.data) ? received.data[0] : received?.data;
+    const attributes = data?.attributes ?? {};
+    const hasAttribute = attributeName in attributes;
+    const actualValue = attributes[attributeName];
+
+    if (expectedValue === undefined) {
+      // Just check existence
+      return {
+        pass: hasAttribute,
+        message: () =>
+          hasAttribute
+            ? `Expected response not to have JSON:API attribute "${attributeName}"`
+            : `Expected response to have JSON:API attribute "${attributeName}", but it was not found. Available attributes: ${Object.keys(attributes).join(", ") || "none"}`,
+      };
+    }
+
+    const valuesMatch = actualValue === expectedValue;
+    return {
+      pass: hasAttribute && valuesMatch,
+      message: () =>
+        hasAttribute && valuesMatch
+          ? `Expected response not to have JSON:API attribute "${attributeName}" with value "${expectedValue}"`
+          : !hasAttribute
+            ? `Expected response to have JSON:API attribute "${attributeName}", but it was not found`
+            : `Expected JSON:API attribute "${attributeName}" to be "${expectedValue}", but got "${actualValue}"`,
+    };
+  },
+
+  /**
+   * Asserts that the response data has the specified relationship.
+   */
+  toHaveJsonApiRelationship(received: JsonApiResponse, relationshipName: string) {
+    const data = Array.isArray(received?.data) ? received.data[0] : received?.data;
+    const relationships = data?.relationships ?? {};
+    const hasRelationship = relationshipName in relationships;
+
+    return {
+      pass: hasRelationship,
+      message: () =>
+        hasRelationship
+          ? `Expected response not to have JSON:API relationship "${relationshipName}"`
+          : `Expected response to have JSON:API relationship "${relationshipName}", but it was not found. Available relationships: ${Object.keys(relationships).join(", ") || "none"}`,
+    };
+  },
+
+  /**
+   * Asserts that the response data array has the expected length.
+   */
+  toHaveJsonApiLength(received: JsonApiResponse, expectedLength: number) {
+    const data = received?.data;
+    const isArray = Array.isArray(data);
+    const actualLength = isArray ? data.length : data ? 1 : 0;
+    const pass = actualLength === expectedLength;
+
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `Expected response not to have ${expectedLength} items`
+          : `Expected response to have ${expectedLength} items, but got ${actualLength}`,
+    };
+  },
+};
+
+// Type declarations for the custom matchers
+declare module "vitest" {
+  interface Assertion<T = any> {
+    toBeValidJsonApi(): T;
+    toHaveJsonApiType(expectedType: string): T;
+    toHaveJsonApiAttribute(attributeName: string, expectedValue?: any): T;
+    toHaveJsonApiRelationship(relationshipName: string): T;
+    toHaveJsonApiLength(expectedLength: number): T;
+  }
+  interface AsymmetricMatchersContaining {
+    toBeValidJsonApi(): any;
+    toHaveJsonApiType(expectedType: string): any;
+    toHaveJsonApiAttribute(attributeName: string, expectedValue?: any): any;
+    toHaveJsonApiRelationship(relationshipName: string): any;
+    toHaveJsonApiLength(expectedLength: number): any;
+  }
+}
+
+/**
+ * Extends Vitest's expect with JSON:API matchers.
+ * Call this in your test setup file.
+ *
+ * @example
+ * ```ts
+ * // vitest.setup.ts
+ * import { extendExpectWithJsonApiMatchers } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * extendExpectWithJsonApiMatchers();
+ * ```
+ */
+export function extendExpectWithJsonApiMatchers(): void {
+  expect.extend(jsonApiMatchers);
+}

package/src/testing/providers/MockJsonApiProvider.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import React from "react";
+import { JsonApiConfig, JsonApiContext } from "../../client/context/JsonApiContext";
+
+export interface MockJsonApiProviderProps {
+  children: React.ReactNode;
+  config?: Partial<JsonApiConfig>;
+}
+
+const defaultMockConfig: JsonApiConfig = {
+  apiUrl: "https://api.test.com",
+  tokenGetter: async () => "mock-token-for-testing",
+  languageGetter: async () => "en",
+  defaultHeaders: {},
+  onError: () => {},
+  cacheConfig: {
+    defaultProfile: "default",
+  },
+};
+
+/**
+ * A test-friendly provider that wraps components with mock JSON:API context.
+ *
+ * @example
+ * ```tsx
+ * import { MockJsonApiProvider } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * render(
+ *   <MockJsonApiProvider>
+ *     <MyComponent />
+ *   </MockJsonApiProvider>
+ * );
+ * ```
+ *
+ * @example With custom config
+ * ```tsx
+ * render(
+ *   <MockJsonApiProvider config={{ apiUrl: 'https://custom.api.com' }}>
+ *     <MyComponent />
+ *   </MockJsonApiProvider>
+ * );
+ * ```
+ */
+export function MockJsonApiProvider({ children, config }: MockJsonApiProviderProps) {
+  const mergedConfig: JsonApiConfig = {
+    ...defaultMockConfig,
+    ...config,
+  };
+
+  return (
+    <JsonApiContext.Provider value={mergedConfig}>
+      {children}
+    </JsonApiContext.Provider>
+  );
+}
+
+export { defaultMockConfig };

package/src/testing/utils/renderWithProviders.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import React, { ReactElement } from "react";
+import { render, RenderOptions, RenderResult } from "@testing-library/react";
+import { MockJsonApiProvider, MockJsonApiProviderProps } from "../providers/MockJsonApiProvider";
+import { JsonApiConfig } from "../../client/context/JsonApiContext";
+
+export interface RenderWithProvidersOptions extends Omit<RenderOptions, "wrapper"> {
+  /**
+   * Custom JSON:API configuration to pass to the mock provider.
+   */
+  jsonApiConfig?: Partial<JsonApiConfig>;
+
+  /**
+   * Additional wrapper component to wrap around the providers.
+   */
+  wrapper?: React.ComponentType<{ children: React.ReactNode }>;
+}
+
+/**
+ * Renders a component wrapped with all necessary providers for testing.
+ *
+ * @example
+ * ```tsx
+ * import { renderWithProviders } from '@carlonicora/nextjs-jsonapi/testing';
+ *
+ * const { getByText } = renderWithProviders(<MyComponent />);
+ * expect(getByText('Hello')).toBeInTheDocument();
+ * ```
+ *
+ * @example With custom config
+ * ```tsx
+ * const { getByText } = renderWithProviders(<MyComponent />, {
+ *   jsonApiConfig: { apiUrl: 'https://custom.api.com' },
+ * });
+ * ```
+ *
+ * @example With additional wrapper
+ * ```tsx
+ * const CustomWrapper = ({ children }) => (
+ *   <ThemeProvider>{children}</ThemeProvider>
+ * );
+ *
+ * const { getByText } = renderWithProviders(<MyComponent />, {
+ *   wrapper: CustomWrapper,
+ * });
+ * ```
+ */
+export function renderWithProviders(
+  ui: ReactElement,
+  options: RenderWithProvidersOptions = {}
+): RenderResult {
+  const { jsonApiConfig, wrapper: AdditionalWrapper, ...renderOptions } = options;
+
+  function AllProviders({ children }: { children: React.ReactNode }) {
+    const content = (
+      <MockJsonApiProvider config={jsonApiConfig}>
+        {children}
+      </MockJsonApiProvider>
+    );
+
+    if (AdditionalWrapper) {
+      return <AdditionalWrapper>{content}</AdditionalWrapper>;
+    }
+
+    return content;
+  }
+
+  return render(ui, { wrapper: AllProviders, ...renderOptions });
+}
+
+/**
+ * Re-export render utilities from Testing Library for convenience.
+ */
+export { render, screen, waitFor, fireEvent, within } from "@testing-library/react";
+export { userEvent } from "@testing-library/user-event";