@youversion/platform-react-hooks 1.18.1 → 1.20.0

package/src/useChapters.test.tsx

@@ -1,15 +1,13 @@
 import { renderHook, waitFor, act } from '@testing-library/react';
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import type { ReactNode } from 'react';
+import { describe, expect, vi, beforeEach, it } from 'vitest';
 import { useChapters } from './useChapters';
-import { YouVersionContext } from './context';
 import { type BibleClient, type BibleChapter, type Collection } from '@youversion/platform-core';
 import { useBibleClient } from './useBibleClient';
+import { createYVWrapper } from './test/utils';
 
 vi.mock('./useBibleClient');
 
 describe('useChapters', () => {
-  const mockAppKey = 'test-app-key';
   const mockGetChapters = vi.fn();
 
   const mockChapters: Collection<BibleChapter> = {
@@ -21,15 +19,7 @@ describe('useChapters', () => {
     next_page_token: null,
   };
 
-  const createWrapper = (contextValue: { appKey: string }) => {
-    return ({ children }: { children: ReactNode }) => (
-      <YouVersionContext.Provider value={contextValue}>{children}</YouVersionContext.Provider>
-    );
-  };
-
   beforeEach(() => {
-    vi.resetAllMocks();
-
     mockGetChapters.mockResolvedValue(mockChapters);
 
     const mockClient: Partial<BibleClient> = { getChapters: mockGetChapters };
@@ -38,10 +28,7 @@ describe('useChapters', () => {
 
   describe('fetching chapters', () => {
     it('should fetch chapters with versionId, book params', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useChapters(111, 'MAT'), { wrapper });
 
       expect(result.current.loading).toBe(true);
@@ -51,73 +38,58 @@ describe('useChapters', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetChapters).toHaveBeenCalledWith(111, 'MAT');
-      expect(result.current.chapters).toEqual(mockChapters);
-    });
-
-    it('should refetch when versionId changes', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
-      const { result, rerender } = renderHook(({ versionId }) => useChapters(versionId, 'MAT'), {
-        wrapper,
-        initialProps: { versionId: 1 },
-      });
-
-      await waitFor(() => {
-        expect(result.current.loading).toBe(false);
-      });
-
-      expect(mockGetChapters).toHaveBeenCalledTimes(1);
-      expect(mockGetChapters).toHaveBeenLastCalledWith(1, 'MAT');
-
-      act(() => {
-        rerender({ versionId: 111 });
-      });
-
-      await waitFor(() => {
-        expect(result.current.loading).toBe(false);
-      });
-
-      expect(mockGetChapters).toHaveBeenCalledTimes(2);
-      expect(mockGetChapters).toHaveBeenLastCalledWith(111, 'MAT');
+      expect.soft(mockGetChapters).toHaveBeenCalledWith(111, 'MAT');
+      expect.soft(result.current.chapters).toEqual(mockChapters);
     });
 
-    it('should refetch when book changes', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
-      const { result, rerender } = renderHook(({ book }) => useChapters(1, book), {
-        wrapper,
-        initialProps: { book: 'MAT' },
-      });
-
-      await waitFor(() => {
-        expect(result.current.loading).toBe(false);
-      });
-
-      expect(mockGetChapters).toHaveBeenCalledTimes(1);
-      expect(mockGetChapters).toHaveBeenLastCalledWith(1, 'MAT');
-
-      act(() => {
-        rerender({ book: 'GEN' });
-      });
-
-      await waitFor(() => {
-        expect(result.current.loading).toBe(false);
-      });
-
-      expect(mockGetChapters).toHaveBeenCalledTimes(2);
-      expect(mockGetChapters).toHaveBeenLastCalledWith(1, 'GEN');
-    });
+    it.each([
+      {
+        param: 'versionId',
+        HookFn: ({ val }: { val: number | string }) => useChapters(val as number, 'MAT'),
+        initial: { val: 1 },
+        updated: { val: 111 },
+        expectedInitial: [1, 'MAT'],
+        expectedUpdated: [111, 'MAT'],
+      },
+      {
+        param: 'book',
+        HookFn: ({ val }: { val: number | string }) => useChapters(1, val as string),
+        initial: { val: 'MAT' },
+        updated: { val: 'GEN' },
+        expectedInitial: [1, 'MAT'],
+        expectedUpdated: [1, 'GEN'],
+      },
+    ])(
+      'should refetch when $param changes',
+      async ({ HookFn, initial, updated, expectedInitial, expectedUpdated }) => {
+        const wrapper = createYVWrapper();
+        const { result, rerender } = renderHook(HookFn, {
+          wrapper,
+          initialProps: initial,
+        });
+
+        await waitFor(() => {
+          expect(result.current.loading).toBe(false);
+        });
+
+        expect.soft(mockGetChapters).toHaveBeenCalledTimes(1);
+        expect.soft(mockGetChapters).toHaveBeenLastCalledWith(...expectedInitial);
+
+        act(() => {
+          rerender(updated);
+        });
+
+        await waitFor(() => {
+          expect(result.current.loading).toBe(false);
+        });
+
+        expect.soft(mockGetChapters).toHaveBeenCalledTimes(2);
+        expect.soft(mockGetChapters).toHaveBeenLastCalledWith(...expectedUpdated);
+      },
+    );
 
     it('should not fetch when enabled is false', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useChapters(1, 'MAT', { enabled: false }), {
         wrapper,
       });
@@ -126,44 +98,38 @@ describe('useChapters', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetChapters).not.toHaveBeenCalled();
-      expect(result.current.chapters).toBe(null);
+      expect.soft(mockGetChapters).not.toHaveBeenCalled();
+      expect.soft(result.current.chapters).toBe(null);
     });
 
     it('should handle fetch errors', async () => {
+      const wrapper = createYVWrapper();
       const error = new Error('Failed to fetch chapters');
       mockGetChapters.mockRejectedValueOnce(error);
 
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
       const { result } = renderHook(() => useChapters(1, 'MAT'), { wrapper });
 
       await waitFor(() => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(result.current.error).toEqual(error);
-      expect(result.current.chapters).toBe(null);
+      expect.soft(result.current.error).toEqual(error);
+      expect.soft(result.current.chapters).toBe(null);
     });
 
     it('should clear error on successful refetch', async () => {
+      const wrapper = createYVWrapper();
       const error = new Error('Failed to fetch chapters');
       mockGetChapters.mockRejectedValueOnce(error).mockResolvedValueOnce(mockChapters);
 
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
       const { result } = renderHook(() => useChapters(1, 'MAT'), { wrapper });
 
       await waitFor(() => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(result.current.error).toEqual(error);
-      expect(result.current.chapters).toBe(null);
+      expect.soft(result.current.error).toEqual(error);
+      expect.soft(result.current.chapters).toBe(null);
 
       act(() => {
         result.current.refetch();
@@ -173,15 +139,12 @@ describe('useChapters', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(result.current.error).toBe(null);
-      expect(result.current.chapters).toEqual(mockChapters);
+      expect.soft(result.current.error).toBe(null);
+      expect.soft(result.current.chapters).toEqual(mockChapters);
     });
 
     it('should support manual refetch', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useChapters(1, 'MAT'), { wrapper });
 
       await waitFor(() => {
@@ -201,56 +164,23 @@ describe('useChapters', () => {
   });
 
   describe('book validation', () => {
-    it('should skip fetch when book is "undefined" string', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
-      const { result } = renderHook(() => useChapters(1, 'undefined'), { wrapper });
-
-      await waitFor(() => {
-        expect(result.current.loading).toBe(false);
-      });
-
-      expect(mockGetChapters).not.toHaveBeenCalled();
-      expect(result.current.chapters).toBe(null);
-    });
-
-    it('should skip fetch when book is "null" string', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
-      const { result } = renderHook(() => useChapters(1, 'null'), { wrapper });
-
-      await waitFor(() => {
-        expect(result.current.loading).toBe(false);
-      });
-
-      expect(mockGetChapters).not.toHaveBeenCalled();
-      expect(result.current.chapters).toBe(null);
-    });
-
-    it('should skip fetch when book is empty string', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
-      const { result } = renderHook(() => useChapters(1, ''), { wrapper });
-
-      await waitFor(() => {
-        expect(result.current.loading).toBe(false);
-      });
-
-      expect(mockGetChapters).not.toHaveBeenCalled();
-      expect(result.current.chapters).toBe(null);
-    });
+    it.each([{ invalidBook: 'undefined' }, { invalidBook: 'null' }, { invalidBook: '' }])(
+      'should skip fetch when book is "$invalidBook"',
+      async ({ invalidBook }) => {
+        const wrapper = createYVWrapper();
+        const { result } = renderHook(() => useChapters(1, invalidBook), { wrapper });
+
+        await waitFor(() => {
+          expect(result.current.loading).toBe(false);
+        });
+
+        expect.soft(mockGetChapters).not.toHaveBeenCalled();
+        expect.soft(result.current.chapters).toBe(null);
+      },
+    );
 
     it('should fetch when book changes from invalid to valid', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result, rerender } = renderHook(({ book }) => useChapters(1, book), {
         wrapper,
         initialProps: { book: 'undefined' },
@@ -270,9 +200,9 @@ describe('useChapters', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetChapters).toHaveBeenCalledTimes(1);
-      expect(mockGetChapters).toHaveBeenCalledWith(1, 'MAT');
-      expect(result.current.chapters).toEqual(mockChapters);
+      expect.soft(mockGetChapters).toHaveBeenCalledTimes(1);
+      expect.soft(mockGetChapters).toHaveBeenCalledWith(1, 'MAT');
+      expect.soft(result.current.chapters).toEqual(mockChapters);
     });
   });
 });

package/src/useHighlights.test.tsx

@@ -1,5 +1,5 @@
 import { renderHook, waitFor } from '@testing-library/react';
-import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { describe, expect, vi, beforeEach, it, type Mock } from 'vitest';
 import type { ReactNode } from 'react';
 import { useHighlights } from './useHighlights';
 import { YouVersionContext } from './context';
@@ -10,8 +10,8 @@ import {
   type Highlight,
   type CreateHighlight,
 } from '@youversion/platform-core';
+import { createYVWrapper } from './test/utils';
 
-// Mock the core package
 vi.mock('@youversion/platform-core', async () => {
   const actual = await vi.importActual('@youversion/platform-core');
   return {
@@ -26,8 +26,6 @@ vi.mock('@youversion/platform-core', async () => {
 });
 
 describe('useHighlights', () => {
-  const mockAppKey = 'test-app-key';
-
   const mockHighlights: Collection<Highlight> = {
     data: [
       {
@@ -54,15 +52,7 @@ describe('useHighlights', () => {
   let mockCreateHighlight: Mock;
   let mockDeleteHighlight: Mock;
 
-  const createWrapper = (contextValue: { appKey: string }) => {
-    return ({ children }: { children: ReactNode }) => (
-      <YouVersionContext.Provider value={contextValue}>{children}</YouVersionContext.Provider>
-    );
-  };
-
   beforeEach(() => {
-    vi.clearAllMocks();
-
     mockGetHighlights = vi.fn().mockResolvedValue(mockHighlights);
     mockCreateHighlight = vi.fn().mockResolvedValue(mockHighlight);
     mockDeleteHighlight = vi.fn().mockResolvedValue(undefined);
@@ -88,47 +78,30 @@ describe('useHighlights', () => {
         'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
       );
     });
-
-    it('should throw error when appKey is missing', () => {
-      const wrapper = createWrapper({
-        appKey: '',
-      });
-
-      expect(() => renderHook(() => useHighlights(), { wrapper })).toThrow(
-        'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
-      );
-    });
   });
 
   describe('client creation', () => {
     it('should create HighlightsClient with correct ApiClient config', () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       renderHook(() => useHighlights(), { wrapper });
 
       expect(ApiClient).toHaveBeenCalledWith({
-        appKey: mockAppKey,
+        appKey: 'test-app-key',
       });
       expect(HighlightsClient).toHaveBeenCalledWith(expect.objectContaining({ isApiClient: true }));
     });
 
     it('should memoize HighlightsClient instance', () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { rerender } = renderHook(() => useHighlights(), { wrapper });
 
       rerender();
 
-      // If client is memoized, refetch should be stable (though useCallback might still create new refs)
       expect(HighlightsClient).toHaveBeenCalledTimes(1);
     });
 
     it('should create new HighlightsClient when context values change', () => {
-      let currentAppKey = mockAppKey;
+      let currentAppKey = 'test-app-key';
 
       const wrapper = ({ children }: { children: ReactNode }) => (
         <YouVersionContext.Provider
@@ -154,10 +127,7 @@ describe('useHighlights', () => {
 
   describe('fetching highlights', () => {
     it('should fetch highlights with no options', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       expect(result.current.loading).toBe(true);
@@ -167,45 +137,36 @@ describe('useHighlights', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetHighlights).toHaveBeenCalledWith(undefined);
-      expect(result.current.highlights).toEqual(mockHighlights);
+      expect.soft(mockGetHighlights).toHaveBeenCalledWith(undefined);
+      expect.soft(result.current.highlights).toEqual(mockHighlights);
     });
 
     it('should fetch highlights with version_id option', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights({ version_id: 111 }), { wrapper });
 
       await waitFor(() => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetHighlights).toHaveBeenCalledWith({ version_id: 111 });
-      expect(result.current.highlights).toEqual(mockHighlights);
+      expect.soft(mockGetHighlights).toHaveBeenCalledWith({ version_id: 111 });
+      expect.soft(result.current.highlights).toEqual(mockHighlights);
     });
 
     it('should fetch highlights with passage_id option', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights({ passage_id: 'MAT.1.1' }), { wrapper });
 
       await waitFor(() => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetHighlights).toHaveBeenCalledWith({ passage_id: 'MAT.1.1' });
-      expect(result.current.highlights).toEqual(mockHighlights);
+      expect.soft(mockGetHighlights).toHaveBeenCalledWith({ passage_id: 'MAT.1.1' });
+      expect.soft(result.current.highlights).toEqual(mockHighlights);
     });
 
     it('should fetch highlights with both options', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(
         () => useHighlights({ version_id: 111, passage_id: 'MAT.1.1' }),
         {
@@ -217,18 +178,15 @@ describe('useHighlights', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetHighlights).toHaveBeenCalledWith({
+      expect.soft(mockGetHighlights).toHaveBeenCalledWith({
         version_id: 111,
         passage_id: 'MAT.1.1',
       });
-      expect(result.current.highlights).toEqual(mockHighlights);
+      expect.soft(result.current.highlights).toEqual(mockHighlights);
     });
 
     it('should refetch when options change', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result, rerender } = renderHook(({ options }) => useHighlights(options), {
         wrapper,
         initialProps: { options: { version_id: 111 } },
@@ -246,15 +204,12 @@ describe('useHighlights', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetHighlights).toHaveBeenCalledTimes(2);
-      expect(mockGetHighlights).toHaveBeenLastCalledWith({ version_id: 1 });
+      expect.soft(mockGetHighlights).toHaveBeenCalledTimes(2);
+      expect.soft(mockGetHighlights).toHaveBeenLastCalledWith({ version_id: 1 });
     });
 
     it('should not fetch when enabled is false', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights(undefined, { enabled: false }), {
         wrapper,
       });
@@ -263,33 +218,27 @@ describe('useHighlights', () => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(mockGetHighlights).not.toHaveBeenCalled();
-      expect(result.current.highlights).toBe(null);
+      expect.soft(mockGetHighlights).not.toHaveBeenCalled();
+      expect.soft(result.current.highlights).toBe(null);
     });
 
     it('should handle fetch errors', async () => {
+      const wrapper = createYVWrapper();
       const error = new Error('Failed to fetch highlights');
       mockGetHighlights.mockRejectedValueOnce(error);
 
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       await waitFor(() => {
         expect(result.current.loading).toBe(false);
       });
 
-      expect(result.current.error).toEqual(error);
-      expect(result.current.highlights).toBe(null);
+      expect.soft(result.current.error).toEqual(error);
+      expect.soft(result.current.highlights).toBe(null);
     });
 
     it('should support manual refetch', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       await waitFor(() => {
@@ -308,10 +257,7 @@ describe('useHighlights', () => {
 
   describe('createHighlight mutation', () => {
     it('should create highlight and refetch', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       await waitFor(() => {
@@ -333,20 +279,16 @@ describe('useHighlights', () => {
       const created = await createPromise;
       expect(created).toEqual(mockHighlight);
 
-      // Should refetch after creation
       await waitFor(() => {
         expect(mockGetHighlights).toHaveBeenCalledTimes(2);
       });
     });
 
     it('should handle create error', async () => {
+      const wrapper = createYVWrapper();
       const error = new Error('Failed to create highlight');
       mockCreateHighlight.mockRejectedValueOnce(error);
 
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       await waitFor(() => {
@@ -363,17 +305,13 @@ describe('useHighlights', () => {
         'Failed to create highlight',
       );
 
-      // Should not refetch on error
       expect(mockGetHighlights).toHaveBeenCalledTimes(1);
     });
   });
 
   describe('deleteHighlight mutation', () => {
     it('should delete highlight and refetch', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       await waitFor(() => {
@@ -388,17 +326,13 @@ describe('useHighlights', () => {
 
       await deletePromise;
 
-      // Should refetch after deletion
       await waitFor(() => {
         expect(mockGetHighlights).toHaveBeenCalledTimes(2);
       });
     });
 
     it('should delete highlight with options', async () => {
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
+      const wrapper = createYVWrapper();
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       await waitFor(() => {
@@ -413,18 +347,14 @@ describe('useHighlights', () => {
 
       await deletePromise;
 
-      // Should refetch after deletion
       expect(mockGetHighlights).toHaveBeenCalledTimes(2);
     });
 
     it('should handle delete error', async () => {
+      const wrapper = createYVWrapper();
       const error = new Error('Failed to delete highlight');
       mockDeleteHighlight.mockRejectedValueOnce(error);
 
-      const wrapper = createWrapper({
-        appKey: mockAppKey,
-      });
-
       const { result } = renderHook(() => useHighlights(), { wrapper });
 
       await waitFor(() => {
@@ -435,7 +365,6 @@ describe('useHighlights', () => {
         'Failed to delete highlight',
       );
 
-      // Should not refetch on error
       expect(mockGetHighlights).toHaveBeenCalledTimes(1);
     });
   });

package/src/useInitData.ts

@@ -22,6 +22,10 @@ interface InitData {
   chapter: BibleChapter;
 }
 
+/**
+ * @deprecated This hook will be removed in the next major version.
+ * Use `useVersion`, `useBook`, and `useChapter` directly instead.
+ */
 export function useInitData(
   { version, book, chapter }: Props = {
     version: DEFAULT.VERSION,