test(web): strengthen nuqs testing infrastructure and documentation (#32340)

Replace hand-written URL parse/serialize logic in
useDocumentListQueryState with nuqs useQueryStates, reducing boilerplate
and fixing the keyword double-encoding bug. The detail page now reads
search params via useSearchParams() instead of window.location.search,
and interactive elements use semantic <button> with Tailwind icon classes.

- Replace parseParams/updateSearchParams with nuqs createParser parsers
- Stabilise updateQuery callback deps (setQuery only, no query/router)
- Add parseAsKeyword with backward-compat decodeURIComponent for legacy
  double-encoded URLs
- Replace RiArrowLeftLine/RiLayoutLeft2Line with Tailwind CSS icon spans
- Use data-testid selectors in detail tests instead of fragile DOM walks
- Rewrite query state tests to use NuqsTestingAdapter

.agents/skills/frontend-testing/SKILL.md

@@ -204,6 +204,16 @@ When assigned to test a directory/path, test **ALL content** within that path:
 
 > See [Test Structure Template](#test-structure-template) for correct import/mock patterns.
 
+### `nuqs` Query State Testing (Required for URL State Hooks)
+
+When a component or hook uses `useQueryState` / `useQueryStates`:
+
+- ✅ Use `NuqsTestingAdapter` (prefer shared helpers in `web/test/nuqs-testing.tsx`)
+- ✅ Assert URL synchronization via `onUrlUpdate` (`searchParams`, `options.history`)
+- ✅ For custom parsers (`createParser`), keep `parse` and `serialize` bijective and add round-trip edge cases (`%2F`, `%25`, spaces, legacy encoded values)
+- ✅ Verify default-clearing behavior (default values should be removed from URL when applicable)
+- ⚠️ Only mock `nuqs` directly when URL behavior is explicitly out of scope for the test
+
 ## Core Principles
 
 ### 1. AAA Pattern (Arrange-Act-Assert)

.agents/skills/frontend-testing/references/checklist.md

@@ -80,6 +80,9 @@ Use this checklist when generating or reviewing tests for Dify frontend componen
 - [ ] Router mocks match actual Next.js API
 - [ ] Mocks reflect actual component conditional behavior
 - [ ] Only mock: API services, complex context providers, third-party libs
+- [ ] For `nuqs` URL-state tests, wrap with `NuqsTestingAdapter` (prefer `web/test/nuqs-testing.tsx`)
+- [ ] For `nuqs` URL-state tests, assert `onUrlUpdate` payload (`searchParams`, `options.history`)
+- [ ] If custom `nuqs` parser exists, add round-trip tests for encoded edge cases (`%2F`, `%25`, spaces, legacy encoded values)
 
 ### Queries
 

.agents/skills/frontend-testing/references/mocking.md

@@ -125,6 +125,31 @@ describe('Component', () => {
 })
 ```
 
+### 2.1 `nuqs` Query State (Preferred: Testing Adapter)
+
+For tests that validate URL query behavior, use `NuqsTestingAdapter` instead of mocking `nuqs` directly.
+
+```typescript
+import { renderHookWithNuqs } from '@/test/nuqs-testing'
+
+it('should sync query to URL with push history', async () => {
+  const { result, onUrlUpdate } = renderHookWithNuqs(() => useMyQueryState(), {
+    searchParams: '?page=1',
+  })
+
+  act(() => {
+    result.current.setQuery({ page: 2 })
+  })
+
+  await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+  const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+  expect(update.options.history).toBe('push')
+  expect(update.searchParams.get('page')).toBe('2')
+})
+```
+
+Use direct `vi.mock('nuqs')` only when URL synchronization is intentionally out of scope.
+
 ### 3. Portal Components (with Shared State)
 
 ```typescript

web/__tests__/apps/app-list-browsing-flow.test.tsx

@@ -8,11 +8,11 @@
  */
 import type { AppListResponse } from '@/models/app'
 import type { App } from '@/types/app'
-import { fireEvent, render, screen } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { fireEvent, screen } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import List from '@/app/components/apps/list'
 import { AccessMode } from '@/models/access-control'
+import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 
 let mockIsCurrentWorkspaceEditor = true
@@ -161,10 +161,9 @@ const createPage = (apps: App[], hasMore = false, page = 1): AppListResponse =>
 })
 
 const renderList = (searchParams?: Record<string, string>) => {
-  return render(
-    <NuqsTestingAdapter searchParams={searchParams}>
-      <List controlRefreshList={0} />
-    </NuqsTestingAdapter>,
+  return renderWithNuqs(
+    <List controlRefreshList={0} />,
+    { searchParams },
   )
 }
 
@@ -209,11 +208,7 @@ describe('App List Browsing Flow', () => {
 
     it('should transition from loading to content when data loads', () => {
       mockIsLoading = true
-      const { rerender } = render(
-        <NuqsTestingAdapter>
-          <List controlRefreshList={0} />
-        </NuqsTestingAdapter>,
-      )
+      const { rerender } = renderWithNuqs(<List controlRefreshList={0} />)
 
       const skeletonCards = document.querySelectorAll('.animate-pulse')
       expect(skeletonCards.length).toBeGreaterThan(0)
@@ -224,11 +219,7 @@ describe('App List Browsing Flow', () => {
         createMockApp({ id: 'app-1', name: 'Loaded App' }),
       ])]
 
-      rerender(
-        <NuqsTestingAdapter>
-          <List controlRefreshList={0} />
-        </NuqsTestingAdapter>,
-      )
+      rerender(<List controlRefreshList={0} />)
 
       expect(screen.getByText('Loaded App')).toBeInTheDocument()
     })
@@ -424,17 +415,9 @@ describe('App List Browsing Flow', () => {
     it('should call refetch when controlRefreshList increments', () => {
       mockPages = [createPage([createMockApp()])]
 
-      const { rerender } = render(
-        <NuqsTestingAdapter>
-          <List controlRefreshList={0} />
-        </NuqsTestingAdapter>,
-      )
+      const { rerender } = renderWithNuqs(<List controlRefreshList={0} />)
 
-      rerender(
-        <NuqsTestingAdapter>
-          <List controlRefreshList={1} />
-        </NuqsTestingAdapter>,
-      )
+      rerender(<List controlRefreshList={1} />)
 
       expect(mockRefetch).toHaveBeenCalled()
     })

web/__tests__/apps/create-app-flow.test.tsx

@@ -9,11 +9,11 @@
  */
 import type { AppListResponse } from '@/models/app'
 import type { App } from '@/types/app'
-import { fireEvent, render, screen, waitFor } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { fireEvent, screen, waitFor } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import List from '@/app/components/apps/list'
 import { AccessMode } from '@/models/access-control'
+import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 
 let mockIsCurrentWorkspaceEditor = true
@@ -214,11 +214,7 @@ const createPage = (apps: App[]): AppListResponse => ({
 })
 
 const renderList = () => {
-  return render(
-    <NuqsTestingAdapter>
-      <List controlRefreshList={0} />
-    </NuqsTestingAdapter>,
-  )
+  return renderWithNuqs(<List controlRefreshList={0} />)
 }
 
 describe('Create App Flow', () => {

web/__tests__/datasets/document-management.test.tsx

@@ -7,9 +7,10 @@
  */
 
 import type { SimpleDocumentDetail } from '@/models/datasets'
-import { act, renderHook } from '@testing-library/react'
+import { act, renderHook, waitFor } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { DataSourceType } from '@/models/datasets'
+import { renderHookWithNuqs } from '@/test/nuqs-testing'
 
 const mockPush = vi.fn()
 vi.mock('next/navigation', () => ({
@@ -34,6 +35,10 @@ const { default: useDocumentListQueryState } = await import(
 
 type LocalDoc = SimpleDocumentDetail & { percent?: number }
 
+const renderQueryStateHook = (searchParams = '') => {
+  return renderHookWithNuqs(() => useDocumentListQueryState(), { searchParams })
+}
+
 const createDoc = (overrides?: Partial<LocalDoc>): LocalDoc => ({
   id: `doc-${Math.random().toString(36).slice(2, 8)}`,
   name: 'test-doc.txt',
@@ -85,7 +90,7 @@ describe('Document Management Flow', () => {
 
   describe('URL-based Query State', () => {
     it('should parse default query from empty URL params', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
+      const { result } = renderQueryStateHook()
 
       expect(result.current.query).toEqual({
         page: 1,
@@ -96,31 +101,31 @@ describe('Document Management Flow', () => {
       })
     })
 
-    it('should update query and push to router', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
+    it('should update query and push to router', async () => {
+      const { result, onUrlUpdate } = renderQueryStateHook()
 
       act(() => {
         result.current.updateQuery({ keyword: 'test', page: 2 })
       })
 
-      expect(mockPush).toHaveBeenCalled()
-      // The push call should contain the updated query params
-      const pushUrl = mockPush.mock.calls[0][0] as string
-      expect(pushUrl).toContain('keyword=test')
-      expect(pushUrl).toContain('page=2')
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('push')
+      expect(update.searchParams.get('keyword')).toBe('test')
+      expect(update.searchParams.get('page')).toBe('2')
     })
 
-    it('should reset query to defaults', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
+    it('should reset query to defaults', async () => {
+      const { result, onUrlUpdate } = renderQueryStateHook()
 
       act(() => {
         result.current.resetQuery()
       })
 
-      expect(mockPush).toHaveBeenCalled()
-      // Default query omits default values from URL
-      const pushUrl = mockPush.mock.calls[0][0] as string
-      expect(pushUrl).toBe('/datasets/ds-1/documents')
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.options.history).toBe('push')
+      expect(update.searchParams.toString()).toBe('')
     })
   })
 
@@ -309,7 +314,7 @@ describe('Document Management Flow', () => {
   describe('Cross-Module: Query State → Sort → Selection Pipeline', () => {
     it('should maintain consistent default state across all hooks', () => {
       const docs = [createDoc({ id: 'doc-1' })]
-      const { result: queryResult } = renderHook(() => useDocumentListQueryState())
+      const { result: queryResult } = renderQueryStateHook()
       const { result: sortResult } = renderHook(() => useDocumentSort({
         documents: docs,
         statusFilterValue: queryResult.current.query.status,

web/app/components/apps/__tests__/list.spec.tsx

@@ -1,9 +1,8 @@
 import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
-import type { ReactNode } from 'react'
-import { act, fireEvent, render, screen } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { act, fireEvent, screen } from '@testing-library/react'
 import * as React from 'react'
 import { useStore as useTagStore } from '@/app/components/base/tag-management/store'
+import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 
 import List from '../list'
@@ -186,15 +185,13 @@ beforeAll(() => {
   } as unknown as typeof IntersectionObserver
 })
 
-// Render helper wrapping with NuqsTestingAdapter
+// Render helper wrapping with shared nuqs testing helper.
 const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
 const renderList = (searchParams = '') => {
-  const wrapper = ({ children }: { children: ReactNode }) => (
-    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
-      {children}
-    </NuqsTestingAdapter>
+  return renderWithNuqs(
+    <List />,
+    { searchParams, onUrlUpdate },
   )
-  return render(<List />, { wrapper })
 }
 
 describe('List', () => {
@@ -391,18 +388,10 @@ describe('List', () => {
 
   describe('Edge Cases', () => {
     it('should handle multiple renders without issues', () => {
-      const { rerender } = render(
-        <NuqsTestingAdapter>
-          <List />
-        </NuqsTestingAdapter>,
-      )
+      const { rerender } = renderWithNuqs(<List />)
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
 
-      rerender(
-        <NuqsTestingAdapter>
-          <List />
-        </NuqsTestingAdapter>,
-      )
+      rerender(<List />)
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
     })
 

web/app/components/apps/hooks/__tests__/use-apps-query-state.spec.tsx

@@ -1,18 +1,9 @@
-import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
-import type { ReactNode } from 'react'
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { act, waitFor } from '@testing-library/react'
+import { renderHookWithNuqs } from '@/test/nuqs-testing'
 import useAppsQueryState from '../use-apps-query-state'
 
 const renderWithAdapter = (searchParams = '') => {
-  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
-  const wrapper = ({ children }: { children: ReactNode }) => (
-    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
-      {children}
-    </NuqsTestingAdapter>
-  )
-  const { result } = renderHook(() => useAppsQueryState(), { wrapper })
-  return { result, onUrlUpdate }
+  return renderHookWithNuqs(() => useAppsQueryState(), { searchParams })
 }
 
 describe('useAppsQueryState', () => {

web/app/components/datasets/documents/detail/__tests__/index.spec.tsx

@@ -9,6 +9,7 @@ const mocks = vi.hoisted(() => {
     documentError: null as Error | null,
     documentMetadata: null as Record<string, unknown> | null,
     media: 'desktop' as string,
+    searchParams: '' as string,
   }
   return {
     state,
@@ -26,6 +27,7 @@ const mocks = vi.hoisted(() => {
 // --- External mocks ---
 vi.mock('next/navigation', () => ({
   useRouter: () => ({ push: mocks.push }),
+  useSearchParams: () => new URLSearchParams(mocks.state.searchParams),
 }))
 
 vi.mock('@/hooks/use-breakpoints', () => ({
@@ -193,6 +195,7 @@ describe('DocumentDetail', () => {
     mocks.state.documentError = null
     mocks.state.documentMetadata = null
     mocks.state.media = 'desktop'
+    mocks.state.searchParams = ''
   })
 
   afterEach(() => {
@@ -286,15 +289,23 @@ describe('DocumentDetail', () => {
     })
 
     it('should toggle metadata panel when button clicked', () => {
-      const { container } = render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
       expect(screen.getByTestId('metadata')).toBeInTheDocument()
 
-      const svgs = container.querySelectorAll('svg')
-      const toggleBtn = svgs[svgs.length - 1].closest('button')!
-      fireEvent.click(toggleBtn)
+      fireEvent.click(screen.getByTestId('document-detail-metadata-toggle'))
       expect(screen.queryByTestId('metadata')).not.toBeInTheDocument()
     })
 
+    it('should expose aria semantics for metadata toggle button', () => {
+      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      const toggle = screen.getByTestId('document-detail-metadata-toggle')
+      expect(toggle).toHaveAttribute('aria-label')
+      expect(toggle).toHaveAttribute('aria-pressed', 'true')
+
+      fireEvent.click(toggle)
+      expect(toggle).toHaveAttribute('aria-pressed', 'false')
+    })
+
     it('should pass correct props to Metadata', () => {
       render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
       const metadata = screen.getByTestId('metadata')
@@ -305,20 +316,21 @@ describe('DocumentDetail', () => {
 
   describe('Navigation', () => {
     it('should navigate back when back button clicked', () => {
-      const { container } = render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
-      const backBtn = container.querySelector('svg')!.parentElement!
-      fireEvent.click(backBtn)
+      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      fireEvent.click(screen.getByTestId('document-detail-back-button'))
       expect(mocks.push).toHaveBeenCalledWith('/datasets/ds-1/documents')
     })
 
+    it('should expose aria label for back button', () => {
+      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      expect(screen.getByTestId('document-detail-back-button')).toHaveAttribute('aria-label')
+    })
+
     it('should preserve query params when navigating back', () => {
-      const origLocation = window.location
-      window.history.pushState({}, '', '?page=2&status=active')
-      const { container } = render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
-      const backBtn = container.querySelector('svg')!.parentElement!
-      fireEvent.click(backBtn)
+      mocks.state.searchParams = 'page=2&status=active'
+      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      fireEvent.click(screen.getByTestId('document-detail-back-button'))
       expect(mocks.push).toHaveBeenCalledWith('/datasets/ds-1/documents?page=2&status=active')
-      window.history.pushState({}, '', origLocation.href)
     })
   })
 

web/app/components/datasets/documents/detail/index.tsx

@@ -1,8 +1,7 @@
 'use client'
 import type { FC } from 'react'
 import type { DataSourceInfo, FileItem, FullDocumentDetail, LegacyDataSourceInfo } from '@/models/datasets'
-import { RiArrowLeftLine, RiLayoutLeft2Line, RiLayoutRight2Line } from '@remixicon/react'
-import { useRouter } from 'next/navigation'
+import { useRouter, useSearchParams } from 'next/navigation'
 import * as React from 'react'
 import { useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
@@ -35,6 +34,7 @@ type DocumentDetailProps = {
 
 const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
   const router = useRouter()
+  const searchParams = useSearchParams()
   const { t } = useTranslation()
 
   const media = useBreakpoints()
@@ -98,11 +98,8 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
   })
 
   const backToPrev = () => {
-    // Preserve pagination and filter states when navigating back
-    const searchParams = new URLSearchParams(window.location.search)
     const queryString = searchParams.toString()
-    const separator = queryString ? '?' : ''
-    const backPath = `/datasets/${datasetId}/documents${separator}${queryString}`
+    const backPath = `/datasets/${datasetId}/documents${queryString ? `?${queryString}` : ''}`
     router.push(backPath)
   }
 
@@ -152,6 +149,11 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
     return chunkMode === ChunkingMode.parentChild && parentMode === 'full-doc'
   }, [documentDetail?.doc_form, parentMode])
 
+  const backButtonLabel = t('operation.back', { ns: 'common' })
+  const metadataToggleLabel = `${showMetadata
+    ? t('operation.close', { ns: 'common' })
+    : t('operation.view', { ns: 'common' })} ${t('metadata.title', { ns: 'datasetDocuments' })}`
+
   return (
     <DocumentContext.Provider value={{
       datasetId,
@@ -162,9 +164,19 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
     >
       <div className="flex h-full flex-col bg-background-default">
         <div className="flex min-h-16 flex-wrap items-center justify-between border-b border-b-divider-subtle py-2.5 pl-3 pr-4">
-          <div onClick={backToPrev} className="flex h-8 w-8 shrink-0 cursor-pointer items-center justify-center rounded-full hover:bg-components-button-tertiary-bg">
-            <RiArrowLeftLine className="h-4 w-4 text-components-button-ghost-text hover:text-text-tertiary" />
-          </div>
+          <button
+            type="button"
+            data-testid="document-detail-back-button"
+            aria-label={backButtonLabel}
+            title={backButtonLabel}
+            onClick={backToPrev}
+            className="flex h-8 w-8 shrink-0 cursor-pointer items-center justify-center rounded-full hover:bg-components-button-tertiary-bg"
+          >
+            <span
+              aria-hidden="true"
+              className="i-ri-arrow-left-line h-4 w-4 text-components-button-ghost-text hover:text-text-tertiary"
+            />
+          </button>
           <DocumentTitle
             datasetId={datasetId}
             extension={documentUploadFile?.extension}
@@ -216,13 +228,17 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
             />
             <button
               type="button"
+              data-testid="document-detail-metadata-toggle"
+              aria-label={metadataToggleLabel}
+              aria-pressed={showMetadata}
+              title={metadataToggleLabel}
               className={style.layoutRightIcon}
               onClick={() => setShowMetadata(!showMetadata)}
             >
               {
                 showMetadata
-                  ? <RiLayoutLeft2Line className="h-4 w-4 text-components-button-secondary-text" />
-                  : <RiLayoutRight2Line className="h-4 w-4 text-components-button-secondary-text" />
+                  ? <span aria-hidden="true" className="i-ri-layout-left-2-line h-4 w-4 text-components-button-secondary-text" />
+                  : <span aria-hidden="true" className="i-ri-layout-right-2-line h-4 w-4 text-components-button-secondary-text" />
               }
             </button>
           </div>

web/app/components/datasets/documents/hooks/__tests__/use-document-list-query-state.spec.ts

@@ -1,439 +0,0 @@
-import type { DocumentListQuery } from '../use-document-list-query-state'
-import { act, renderHook } from '@testing-library/react'
-
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import useDocumentListQueryState from '../use-document-list-query-state'
-
-const mockPush = vi.fn()
-const mockSearchParams = new URLSearchParams()
-
-vi.mock('@/models/datasets', () => ({
-  DisplayStatusList: [
-    'queuing',
-    'indexing',
-    'paused',
-    'error',
-    'available',
-    'enabled',
-    'disabled',
-    'archived',
-  ],
-}))
-
-vi.mock('next/navigation', () => ({
-  useRouter: () => ({ push: mockPush }),
-  usePathname: () => '/datasets/test-id/documents',
-  useSearchParams: () => mockSearchParams,
-}))
-
-describe('useDocumentListQueryState', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-    // Reset mock search params to empty
-    for (const key of [...mockSearchParams.keys()])
-      mockSearchParams.delete(key)
-  })
-
-  // Tests for parseParams (exposed via the query property)
-  describe('parseParams (via query)', () => {
-    it('should return default query when no search params present', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query).toEqual({
-        page: 1,
-        limit: 10,
-        keyword: '',
-        status: 'all',
-        sort: '-created_at',
-      })
-    })
-
-    it('should parse page from search params', () => {
-      mockSearchParams.set('page', '3')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.page).toBe(3)
-    })
-
-    it('should default page to 1 when page is zero', () => {
-      mockSearchParams.set('page', '0')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.page).toBe(1)
-    })
-
-    it('should default page to 1 when page is negative', () => {
-      mockSearchParams.set('page', '-5')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.page).toBe(1)
-    })
-
-    it('should default page to 1 when page is NaN', () => {
-      mockSearchParams.set('page', 'abc')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.page).toBe(1)
-    })
-
-    it('should parse limit from search params', () => {
-      mockSearchParams.set('limit', '50')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.limit).toBe(50)
-    })
-
-    it('should default limit to 10 when limit is zero', () => {
-      mockSearchParams.set('limit', '0')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.limit).toBe(10)
-    })
-
-    it('should default limit to 10 when limit exceeds 100', () => {
-      mockSearchParams.set('limit', '101')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.limit).toBe(10)
-    })
-
-    it('should default limit to 10 when limit is negative', () => {
-      mockSearchParams.set('limit', '-1')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.limit).toBe(10)
-    })
-
-    it('should accept limit at boundary 100', () => {
-      mockSearchParams.set('limit', '100')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.limit).toBe(100)
-    })
-
-    it('should accept limit at boundary 1', () => {
-      mockSearchParams.set('limit', '1')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.limit).toBe(1)
-    })
-
-    it('should parse and decode keyword from search params', () => {
-      mockSearchParams.set('keyword', encodeURIComponent('hello world'))
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.keyword).toBe('hello world')
-    })
-
-    it('should return empty keyword when not present', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.keyword).toBe('')
-    })
-
-    it('should sanitize status from search params', () => {
-      mockSearchParams.set('status', 'available')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.status).toBe('available')
-    })
-
-    it('should fallback status to all for unknown status', () => {
-      mockSearchParams.set('status', 'badvalue')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.status).toBe('all')
-    })
-
-    it('should resolve active status alias to available', () => {
-      mockSearchParams.set('status', 'active')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.status).toBe('available')
-    })
-
-    it('should parse valid sort value from search params', () => {
-      mockSearchParams.set('sort', 'hit_count')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.sort).toBe('hit_count')
-    })
-
-    it('should default sort to -created_at for invalid sort value', () => {
-      mockSearchParams.set('sort', 'invalid_sort')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.sort).toBe('-created_at')
-    })
-
-    it('should default sort to -created_at when not present', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.sort).toBe('-created_at')
-    })
-
-    it.each([
-      '-created_at',
-      'created_at',
-      '-hit_count',
-      'hit_count',
-    ] as const)('should accept valid sort value %s', (sortValue) => {
-      mockSearchParams.set('sort', sortValue)
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current.query.sort).toBe(sortValue)
-    })
-  })
-
-  // Tests for updateQuery
-  describe('updateQuery', () => {
-    it('should call router.push with updated params when page is changed', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ page: 3 })
-      })
-
-      expect(mockPush).toHaveBeenCalledTimes(1)
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toContain('page=3')
-    })
-
-    it('should call router.push with scroll false', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ page: 2 })
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.any(String),
-        { scroll: false },
-      )
-    })
-
-    it('should set status in URL when status is not all', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ status: 'error' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toContain('status=error')
-    })
-
-    it('should not set status in URL when status is all', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ status: 'all' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).not.toContain('status=')
-    })
-
-    it('should set sort in URL when sort is not the default -created_at', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ sort: 'hit_count' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toContain('sort=hit_count')
-    })
-
-    it('should not set sort in URL when sort is default -created_at', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ sort: '-created_at' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).not.toContain('sort=')
-    })
-
-    it('should encode keyword in URL when keyword is provided', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ keyword: 'test query' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      // Source code applies encodeURIComponent before setting in URLSearchParams
-      expect(pushedUrl).toContain('keyword=')
-      const params = new URLSearchParams(pushedUrl.split('?')[1])
-      // params.get decodes one layer, but the value was pre-encoded with encodeURIComponent
-      expect(decodeURIComponent(params.get('keyword')!)).toBe('test query')
-    })
-
-    it('should remove keyword from URL when keyword is empty', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ keyword: '' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).not.toContain('keyword=')
-    })
-
-    it('should sanitize invalid status to all and not include in URL', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ status: 'invalidstatus' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).not.toContain('status=')
-    })
-
-    it('should sanitize invalid sort to -created_at and not include in URL', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ sort: 'invalidsort' as DocumentListQuery['sort'] })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).not.toContain('sort=')
-    })
-
-    it('should omit page and limit when they are default and no keyword', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ page: 1, limit: 10 })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).not.toContain('page=')
-      expect(pushedUrl).not.toContain('limit=')
-    })
-
-    it('should include page and limit when page is greater than 1', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ page: 2 })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toContain('page=2')
-      expect(pushedUrl).toContain('limit=10')
-    })
-
-    it('should include page and limit when limit is non-default', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ limit: 25 })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toContain('page=1')
-      expect(pushedUrl).toContain('limit=25')
-    })
-
-    it('should include page and limit when keyword is provided', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ keyword: 'search' })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toContain('page=1')
-      expect(pushedUrl).toContain('limit=10')
-    })
-
-    it('should use pathname prefix in pushed URL', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({ page: 2 })
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toMatch(/^\/datasets\/test-id\/documents/)
-    })
-
-    it('should push path without query string when all values are defaults', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.updateQuery({})
-      })
-
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      expect(pushedUrl).toBe('/datasets/test-id/documents')
-    })
-  })
-
-  // Tests for resetQuery
-  describe('resetQuery', () => {
-    it('should push URL with default query params when called', () => {
-      mockSearchParams.set('page', '5')
-      mockSearchParams.set('status', 'error')
-
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.resetQuery()
-      })
-
-      expect(mockPush).toHaveBeenCalledTimes(1)
-      const pushedUrl = mockPush.mock.calls[0][0] as string
-      // Default query has all defaults, so no params should be in the URL
-      expect(pushedUrl).toBe('/datasets/test-id/documents')
-    })
-
-    it('should call router.push with scroll false when resetting', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      act(() => {
-        result.current.resetQuery()
-      })
-
-      expect(mockPush).toHaveBeenCalledWith(
-        expect.any(String),
-        { scroll: false },
-      )
-    })
-  })
-
-  // Tests for return value stability
-  describe('return value', () => {
-    it('should return query, updateQuery, and resetQuery', () => {
-      const { result } = renderHook(() => useDocumentListQueryState())
-
-      expect(result.current).toHaveProperty('query')
-      expect(result.current).toHaveProperty('updateQuery')
-      expect(result.current).toHaveProperty('resetQuery')
-      expect(typeof result.current.updateQuery).toBe('function')
-      expect(typeof result.current.resetQuery).toBe('function')
-    })
-  })
-})

web/app/components/datasets/documents/hooks/__tests__/use-document-list-query-state.spec.tsx

@@ -0,0 +1,410 @@
+import type { DocumentListQuery } from '../use-document-list-query-state'
+import { act, waitFor } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { renderHookWithNuqs } from '@/test/nuqs-testing'
+import useDocumentListQueryState from '../use-document-list-query-state'
+
+vi.mock('@/models/datasets', () => ({
+  DisplayStatusList: [
+    'queuing',
+    'indexing',
+    'paused',
+    'error',
+    'available',
+    'enabled',
+    'disabled',
+    'archived',
+  ],
+}))
+
+const renderWithAdapter = (searchParams = '') => {
+  return renderHookWithNuqs(() => useDocumentListQueryState(), { searchParams })
+}
+
+describe('useDocumentListQueryState', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('query parsing', () => {
+    it('should return default query when no search params present', () => {
+      const { result } = renderWithAdapter()
+
+      expect(result.current.query).toEqual({
+        page: 1,
+        limit: 10,
+        keyword: '',
+        status: 'all',
+        sort: '-created_at',
+      })
+    })
+
+    it('should parse page from search params', () => {
+      const { result } = renderWithAdapter('?page=3')
+      expect(result.current.query.page).toBe(3)
+    })
+
+    it('should default page to 1 when page is zero', () => {
+      const { result } = renderWithAdapter('?page=0')
+      expect(result.current.query.page).toBe(1)
+    })
+
+    it('should default page to 1 when page is negative', () => {
+      const { result } = renderWithAdapter('?page=-5')
+      expect(result.current.query.page).toBe(1)
+    })
+
+    it('should default page to 1 when page is NaN', () => {
+      const { result } = renderWithAdapter('?page=abc')
+      expect(result.current.query.page).toBe(1)
+    })
+
+    it('should parse limit from search params', () => {
+      const { result } = renderWithAdapter('?limit=50')
+      expect(result.current.query.limit).toBe(50)
+    })
+
+    it('should default limit to 10 when limit is zero', () => {
+      const { result } = renderWithAdapter('?limit=0')
+      expect(result.current.query.limit).toBe(10)
+    })
+
+    it('should default limit to 10 when limit exceeds 100', () => {
+      const { result } = renderWithAdapter('?limit=101')
+      expect(result.current.query.limit).toBe(10)
+    })
+
+    it('should default limit to 10 when limit is negative', () => {
+      const { result } = renderWithAdapter('?limit=-1')
+      expect(result.current.query.limit).toBe(10)
+    })
+
+    it('should accept limit at boundary 100', () => {
+      const { result } = renderWithAdapter('?limit=100')
+      expect(result.current.query.limit).toBe(100)
+    })
+
+    it('should accept limit at boundary 1', () => {
+      const { result } = renderWithAdapter('?limit=1')
+      expect(result.current.query.limit).toBe(1)
+    })
+
+    it('should parse keyword from search params', () => {
+      const { result } = renderWithAdapter('?keyword=hello+world')
+      expect(result.current.query.keyword).toBe('hello world')
+    })
+
+    it('should preserve legacy double-encoded keyword text after URL decoding', () => {
+      const { result } = renderWithAdapter('?keyword=test%2520query')
+      expect(result.current.query.keyword).toBe('test%20query')
+    })
+
+    it('should return empty keyword when not present', () => {
+      const { result } = renderWithAdapter()
+      expect(result.current.query.keyword).toBe('')
+    })
+
+    it('should sanitize status from search params', () => {
+      const { result } = renderWithAdapter('?status=available')
+      expect(result.current.query.status).toBe('available')
+    })
+
+    it('should fallback status to all for unknown status', () => {
+      const { result } = renderWithAdapter('?status=badvalue')
+      expect(result.current.query.status).toBe('all')
+    })
+
+    it('should resolve active status alias to available', () => {
+      const { result } = renderWithAdapter('?status=active')
+      expect(result.current.query.status).toBe('available')
+    })
+
+    it('should parse valid sort value from search params', () => {
+      const { result } = renderWithAdapter('?sort=hit_count')
+      expect(result.current.query.sort).toBe('hit_count')
+    })
+
+    it('should default sort to -created_at for invalid sort value', () => {
+      const { result } = renderWithAdapter('?sort=invalid_sort')
+      expect(result.current.query.sort).toBe('-created_at')
+    })
+
+    it('should default sort to -created_at when not present', () => {
+      const { result } = renderWithAdapter()
+      expect(result.current.query.sort).toBe('-created_at')
+    })
+
+    it.each([
+      '-created_at',
+      'created_at',
+      '-hit_count',
+      'hit_count',
+    ] as const)('should accept valid sort value %s', (sortValue) => {
+      const { result } = renderWithAdapter(`?sort=${sortValue}`)
+      expect(result.current.query.sort).toBe(sortValue)
+    })
+  })
+
+  describe('updateQuery', () => {
+    it('should update page in state when page is changed', () => {
+      const { result } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ page: 3 })
+      })
+
+      expect(result.current.query.page).toBe(3)
+    })
+
+    it('should sync page to URL with push history', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ page: 2 })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('page')).toBe('2')
+      expect(update.options.history).toBe('push')
+    })
+
+    it('should set status in URL when status is not all', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ status: 'error' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('status')).toBe('error')
+    })
+
+    it('should not set status in URL when status is all', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ status: 'all' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('status')).toBe(false)
+    })
+
+    it('should set sort in URL when sort is not the default -created_at', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ sort: 'hit_count' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('sort')).toBe('hit_count')
+    })
+
+    it('should not set sort in URL when sort is default -created_at', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ sort: '-created_at' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('sort')).toBe(false)
+    })
+
+    it('should set keyword in URL when keyword is provided', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ keyword: 'test query' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('keyword')).toBe('test query')
+    })
+
+    it('should remove keyword from URL when keyword is empty', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?keyword=existing')
+
+      act(() => {
+        result.current.updateQuery({ keyword: '' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('keyword')).toBe(false)
+    })
+
+    it('should remove keyword from URL when keyword contains only whitespace', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?keyword=existing')
+
+      act(() => {
+        result.current.updateQuery({ keyword: '   ' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('keyword')).toBe(false)
+      expect(result.current.query.keyword).toBe('')
+    })
+
+    it('should preserve literal percent-encoded-like keyword values', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ keyword: '%2F' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('keyword')).toBe('%2F')
+      expect(result.current.query.keyword).toBe('%2F')
+    })
+
+    it('should keep keyword text unchanged when updating query from legacy URL', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?keyword=test%2520query')
+
+      act(() => {
+        result.current.updateQuery({ page: 2 })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      expect(result.current.query.keyword).toBe('test%20query')
+    })
+
+    it('should sanitize invalid status to all and not include in URL', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ status: 'invalidstatus' })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('status')).toBe(false)
+    })
+
+    it('should sanitize invalid sort to -created_at and not include in URL', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ sort: 'invalidsort' as DocumentListQuery['sort'] })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('sort')).toBe(false)
+    })
+
+    it('should not include page in URL when page is default', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ page: 1 })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('page')).toBe(false)
+    })
+
+    it('should include page in URL when page is greater than 1', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ page: 2 })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('page')).toBe('2')
+    })
+
+    it('should include limit in URL when limit is non-default', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ limit: 25 })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.get('limit')).toBe('25')
+    })
+
+    it('should sanitize invalid page to default and omit page from URL', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ page: -1 })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('page')).toBe(false)
+      expect(result.current.query.page).toBe(1)
+    })
+
+    it('should sanitize invalid limit to default and omit limit from URL', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter()
+
+      act(() => {
+        result.current.updateQuery({ limit: 999 })
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('limit')).toBe(false)
+      expect(result.current.query.limit).toBe(10)
+    })
+  })
+
+  describe('resetQuery', () => {
+    it('should reset all values to defaults', () => {
+      const { result } = renderWithAdapter('?page=5&status=error&sort=hit_count')
+
+      act(() => {
+        result.current.resetQuery()
+      })
+
+      expect(result.current.query).toEqual({
+        page: 1,
+        limit: 10,
+        keyword: '',
+        status: 'all',
+        sort: '-created_at',
+      })
+    })
+
+    it('should clear all params from URL when called', async () => {
+      const { result, onUrlUpdate } = renderWithAdapter('?page=5&status=error')
+
+      act(() => {
+        result.current.resetQuery()
+      })
+
+      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
+      expect(update.searchParams.has('page')).toBe(false)
+      expect(update.searchParams.has('status')).toBe(false)
+    })
+  })
+
+  describe('return value', () => {
+    it('should return query, updateQuery, and resetQuery', () => {
+      const { result } = renderWithAdapter()
+
+      expect(result.current).toHaveProperty('query')
+      expect(result.current).toHaveProperty('updateQuery')
+      expect(result.current).toHaveProperty('resetQuery')
+      expect(typeof result.current.updateQuery).toBe('function')
+      expect(typeof result.current.resetQuery).toBe('function')
+    })
+  })
+})

web/app/components/datasets/documents/hooks/use-document-list-query-state.ts

@@ -1,6 +1,5 @@
-import type { ReadonlyURLSearchParams } from 'next/navigation'
 import type { SortType } from '@/service/datasets'
-import { usePathname, useRouter, useSearchParams } from 'next/navigation'
+import { createParser, parseAsString, useQueryStates } from 'nuqs'
 import { useCallback, useMemo } from 'react'
 import { sanitizeStatusValue } from '../status-filter'
 
@@ -13,6 +12,14 @@ const sanitizeSortValue = (value?: string | null): SortType => {
   return (ALLOWED_SORT_VALUES.includes(value as SortType) ? value : '-created_at') as SortType
 }
 
+const sanitizePageValue = (value: number): number => {
+  return Number.isInteger(value) && value > 0 ? value : 1
+}
+
+const sanitizeLimitValue = (value: number): number => {
+  return Number.isInteger(value) && value > 0 && value <= 100 ? value : 10
+}
+
 export type DocumentListQuery = {
   page: number
   limit: number
@@ -21,91 +28,65 @@ export type DocumentListQuery = {
   sort: SortType
 }
 
-const DEFAULT_QUERY: DocumentListQuery = {
-  page: 1,
-  limit: 10,
-  keyword: '',
-  status: 'all',
-  sort: '-created_at',
-}
+const parseAsPage = createParser<number>({
+  parse: (value) => {
+    const n = Number.parseInt(value, 10)
+    return Number.isNaN(n) || n <= 0 ? null : n
+  },
+  serialize: value => value.toString(),
+}).withDefault(1)
 
-// Parse the query parameters from the URL search string.
-function parseParams(params: ReadonlyURLSearchParams): DocumentListQuery {
-  const page = Number.parseInt(params.get('page') || '1', 10)
-  const limit = Number.parseInt(params.get('limit') || '10', 10)
-  const keyword = params.get('keyword') || ''
-  const status = sanitizeStatusValue(params.get('status'))
-  const sort = sanitizeSortValue(params.get('sort'))
+const parseAsLimit = createParser<number>({
+  parse: (value) => {
+    const n = Number.parseInt(value, 10)
+    return Number.isNaN(n) || n <= 0 || n > 100 ? null : n
+  },
+  serialize: value => value.toString(),
+}).withDefault(10)
 
-  return {
-    page: page > 0 ? page : 1,
-    limit: (limit > 0 && limit <= 100) ? limit : 10,
-    keyword: keyword ? decodeURIComponent(keyword) : '',
-    status,
-    sort,
-  }
-}
+const parseAsDocStatus = createParser<string>({
+  parse: value => sanitizeStatusValue(value),
+  serialize: value => value,
+}).withDefault('all')
 
-// Update the URL search string with the given query parameters.
-function updateSearchParams(query: DocumentListQuery, searchParams: URLSearchParams) {
-  const { page, limit, keyword, status, sort } = query || {}
+const parseAsDocSort = createParser<SortType>({
+  parse: value => sanitizeSortValue(value),
+  serialize: value => value,
+}).withDefault('-created_at' as SortType)
 
-  const hasNonDefaultParams = (page && page > 1) || (limit && limit !== 10) || (keyword && keyword.trim())
+const parseAsKeyword = parseAsString.withDefault('')
 
-  if (hasNonDefaultParams) {
-    searchParams.set('page', (page || 1).toString())
-    searchParams.set('limit', (limit || 10).toString())
-  }
-  else {
-    searchParams.delete('page')
-    searchParams.delete('limit')
-  }
-
-  if (keyword && keyword.trim())
-    searchParams.set('keyword', encodeURIComponent(keyword))
-  else
-    searchParams.delete('keyword')
-
-  const sanitizedStatus = sanitizeStatusValue(status)
-  if (sanitizedStatus && sanitizedStatus !== 'all')
-    searchParams.set('status', sanitizedStatus)
-  else
-    searchParams.delete('status')
-
-  const sanitizedSort = sanitizeSortValue(sort)
-  if (sanitizedSort !== '-created_at')
-    searchParams.set('sort', sanitizedSort)
-  else
-    searchParams.delete('sort')
+export const documentListParsers = {
+  page: parseAsPage,
+  limit: parseAsLimit,
+  keyword: parseAsKeyword,
+  status: parseAsDocStatus,
+  sort: parseAsDocSort,
 }
 
 function useDocumentListQueryState() {
-  const searchParams = useSearchParams()
-  const query = useMemo(() => parseParams(searchParams), [searchParams])
+  const [query, setQuery] = useQueryStates(documentListParsers, {
+    history: 'push',
+  })
 
-  const router = useRouter()
-  const pathname = usePathname()
-
-  // Helper function to update specific query parameters
   const updateQuery = useCallback((updates: Partial<DocumentListQuery>) => {
-    const newQuery = { ...query, ...updates }
-    newQuery.status = sanitizeStatusValue(newQuery.status)
-    newQuery.sort = sanitizeSortValue(newQuery.sort)
-    const params = new URLSearchParams()
-    updateSearchParams(newQuery, params)
-    const search = params.toString()
-    const queryString = search ? `?${search}` : ''
-    router.push(`${pathname}${queryString}`, { scroll: false })
-  }, [query, router, pathname])
+    const patch = { ...updates }
+    if ('page' in patch && patch.page !== undefined)
+      patch.page = sanitizePageValue(patch.page)
+    if ('limit' in patch && patch.limit !== undefined)
+      patch.limit = sanitizeLimitValue(patch.limit)
+    if ('status' in patch)
+      patch.status = sanitizeStatusValue(patch.status)
+    if ('sort' in patch)
+      patch.sort = sanitizeSortValue(patch.sort)
+    if ('keyword' in patch && typeof patch.keyword === 'string' && patch.keyword.trim() === '')
+      patch.keyword = ''
+    setQuery(patch)
+  }, [setQuery])
 
-  // Helper function to reset query to defaults
   const resetQuery = useCallback(() => {
-    const params = new URLSearchParams()
-    updateSearchParams(DEFAULT_QUERY, params)
-    const search = params.toString()
-    const queryString = search ? `?${search}` : ''
-    router.push(`${pathname}${queryString}`, { scroll: false })
-  }, [router, pathname])
+    setQuery(null)
+  }, [setQuery])
 
   return useMemo(() => ({
     query,

web/app/components/explore/app-list/__tests__/index.spec.tsx

@@ -1,12 +1,12 @@
 import type { Mock } from 'vitest'
 import type { CreateAppModalProps } from '@/app/components/explore/create-app-modal'
 import type { App } from '@/models/explore'
-import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { act, fireEvent, screen, waitFor } from '@testing-library/react'
 import { useAppContext } from '@/context/app-context'
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import { fetchAppDetail } from '@/service/explore'
 import { useMembers } from '@/service/use-common'
+import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 import AppList from '../index'
 
@@ -132,10 +132,9 @@ const mockMemberRole = (hasEditPermission: boolean) => {
 
 const renderAppList = (hasEditPermission = false, onSuccess?: () => void, searchParams?: Record<string, string>) => {
   mockMemberRole(hasEditPermission)
-  return render(
-    <NuqsTestingAdapter searchParams={searchParams}>
-      <AppList onSuccess={onSuccess} />
-    </NuqsTestingAdapter>,
+  return renderWithNuqs(
+    <AppList onSuccess={onSuccess} />,
+    { searchParams },
   )
 }
 

web/app/components/plugins/marketplace/__tests__/atoms.spec.tsx

@@ -1,21 +1,20 @@
-import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
 import type { ReactNode } from 'react'
 import { act, renderHook } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 import { DEFAULT_SORT } from '../constants'
 
 const createWrapper = (searchParams = '') => {
-  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+  const { wrapper: NuqsWrapper } = createNuqsTestWrapper({ searchParams })
   const wrapper = ({ children }: { children: ReactNode }) => (
     <JotaiProvider>
-      <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      <NuqsWrapper>
         {children}
-      </NuqsTestingAdapter>
+      </NuqsWrapper>
     </JotaiProvider>
   )
-  return { wrapper, onUrlUpdate }
+  return { wrapper }
 }
 
 describe('Marketplace sort atoms', () => {

web/app/components/plugins/marketplace/__tests__/plugin-type-switch.spec.tsx

@@ -1,9 +1,8 @@
-import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
 import type { ReactNode } from 'react'
 import { fireEvent, render, screen } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 import PluginTypeSwitch from '../plugin-type-switch'
 
 vi.mock('#i18n', () => ({
@@ -25,15 +24,15 @@ vi.mock('#i18n', () => ({
 }))
 
 const createWrapper = (searchParams = '') => {
-  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+  const { wrapper: NuqsWrapper } = createNuqsTestWrapper({ searchParams })
   const Wrapper = ({ children }: { children: ReactNode }) => (
     <JotaiProvider>
-      <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      <NuqsWrapper>
         {children}
-      </NuqsTestingAdapter>
+      </NuqsWrapper>
     </JotaiProvider>
   )
-  return { Wrapper, onUrlUpdate }
+  return { Wrapper }
 }
 
 describe('PluginTypeSwitch', () => {

web/app/components/plugins/marketplace/__tests__/state.spec.tsx

@@ -2,8 +2,8 @@ import type { ReactNode } from 'react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { renderHook, waitFor } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 
 vi.mock('@/config', () => ({
   API_PREFIX: '/api',
@@ -37,6 +37,7 @@ vi.mock('@/service/client', () => ({
 }))
 
 const createWrapper = (searchParams = '') => {
+  const { wrapper: NuqsWrapper } = createNuqsTestWrapper({ searchParams })
   const queryClient = new QueryClient({
     defaultOptions: {
       queries: { retry: false, gcTime: 0 },
@@ -45,9 +46,9 @@ const createWrapper = (searchParams = '') => {
   const Wrapper = ({ children }: { children: ReactNode }) => (
     <JotaiProvider>
       <QueryClientProvider client={queryClient}>
-        <NuqsTestingAdapter searchParams={searchParams}>
+        <NuqsWrapper>
           {children}
-        </NuqsTestingAdapter>
+        </NuqsWrapper>
       </QueryClientProvider>
     </JotaiProvider>
   )

web/app/components/plugins/marketplace/__tests__/sticky-search-and-switch-wrapper.spec.tsx

@@ -1,8 +1,8 @@
 import type { ReactNode } from 'react'
 import { render } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 import StickySearchAndSwitchWrapper from '../sticky-search-and-switch-wrapper'
 
 vi.mock('#i18n', () => ({
@@ -20,11 +20,12 @@ vi.mock('../search-box/search-box-wrapper', () => ({
   default: () => <div data-testid="search-box-wrapper">SearchBoxWrapper</div>,
 }))
 
+const { wrapper: NuqsWrapper } = createNuqsTestWrapper()
 const Wrapper = ({ children }: { children: ReactNode }) => (
   <JotaiProvider>
-    <NuqsTestingAdapter>
+    <NuqsWrapper>
       {children}
-    </NuqsTestingAdapter>
+    </NuqsWrapper>
   </JotaiProvider>
 )
 

web/app/components/tools/__tests__/provider-list.spec.tsx

@@ -1,6 +1,6 @@
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { cleanup, fireEvent, screen } from '@testing-library/react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { renderWithNuqs } from '@/test/nuqs-testing'
 import { ToolTypeEnum } from '../../workflow/block-selector/types'
 import ProviderList from '../provider-list'
 import { getToolType } from '../utils'
@@ -206,10 +206,9 @@ describe('getToolType', () => {
 })
 
 const renderProviderList = (searchParams?: Record<string, string>) => {
-  return render(
-    <NuqsTestingAdapter searchParams={searchParams}>
-      <ProviderList />
-    </NuqsTestingAdapter>,
+  return renderWithNuqs(
+    <ProviderList />,
+    { searchParams },
   )
 }
 

web/context/modal-context.test.tsx

@@ -1,9 +1,9 @@
-import { act, render, screen, waitFor } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { act, screen, waitFor } from '@testing-library/react'
 import * as React from 'react'
 import { defaultPlan } from '@/app/components/billing/config'
 import { Plan } from '@/app/components/billing/type'
 import { ModalContextProvider } from '@/context/modal-context'
+import { renderWithNuqs } from '@/test/nuqs-testing'
 
 vi.mock('@/config', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@/config')>()
@@ -71,12 +71,10 @@ const createPlan = (overrides: PlanOverrides = {}): PlanShape => ({
   },
 })
 
-const renderProvider = () => render(
-  <NuqsTestingAdapter>
-    <ModalContextProvider>
-      <div data-testid="modal-context-test-child" />
-    </ModalContextProvider>
-  </NuqsTestingAdapter>,
+const renderProvider = () => renderWithNuqs(
+  <ModalContextProvider>
+    <div data-testid="modal-context-test-child" />
+  </ModalContextProvider>,
 )
 
 describe('ModalContextProvider trigger events limit modal', () => {

web/docs/test.md

@@ -225,6 +225,38 @@ Simulate the interactions that matter to users—primary clicks, change events,
 
 Mock the specific Next.js navigation hooks your component consumes (`useRouter`, `usePathname`, `useSearchParams`) and drive realistic routing flows—query parameters, redirects, guarded routes, URL updates—while asserting the rendered outcome or navigation side effects.
 
+#### 7.1 `nuqs` Query State Testing
+
+When testing code that uses `useQueryState` or `useQueryStates`, treat `nuqs` as the source of truth for URL synchronization.
+
+- ✅ In runtime, keep `NuqsAdapter` in app layout (already wired in `app/layout.tsx`).
+- ✅ In tests, wrap with `NuqsTestingAdapter` (prefer helper utilities from `@/test/nuqs-testing`).
+- ✅ Assert URL behavior via `onUrlUpdate` events (`searchParams`, `options.history`) instead of only asserting router mocks.
+- ✅ For custom parsers created with `createParser`, keep `parse` and `serialize` bijective (round-trip safe). Add edge-case coverage for values like `%2F`, `%25`, spaces, and legacy encoded URLs.
+- ✅ Assert default-clearing behavior explicitly (`clearOnDefault` semantics remove params when value equals default).
+- ⚠️ Only mock `nuqs` directly when URL behavior is intentionally out of scope for the test. For ESM-safe partial mocks, use async `vi.mock` with `importOriginal`.
+
+Example:
+
+```tsx
+import { renderHookWithNuqs } from '@/test/nuqs-testing'
+
+it('should update query with push history', async () => {
+  const { result, onUrlUpdate } = renderHookWithNuqs(() => useMyQueryState(), {
+    searchParams: '?page=1',
+  })
+
+  act(() => {
+    result.current.setQuery({ page: 2 })
+  })
+
+  await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
+  const update = onUrlUpdate.mock.calls.at(-1)![0]
+  expect(update.options.history).toBe('push')
+  expect(update.searchParams.get('page')).toBe('2')
+})
+```
+
 ### 8. Edge Cases (REQUIRED - All Components)
 
 **Must Test**:

web/hooks/use-query-params.spec.tsx

@@ -1,8 +1,6 @@
-import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
-import type { ReactNode } from 'react'
-import { act, renderHook, waitFor } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { act, waitFor } from '@testing-library/react'
 import { ACCOUNT_SETTING_MODAL_ACTION } from '@/app/components/header/account-setting/constants'
+import { renderHookWithNuqs } from '@/test/nuqs-testing'
 import {
   clearQueryParams,
   PRICING_MODAL_QUERY_PARAM,
@@ -20,14 +18,7 @@ vi.mock('@/utils/client', () => ({
 }))
 
 const renderWithAdapter = <T,>(hook: () => T, searchParams = '') => {
-  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
-  const wrapper = ({ children }: { children: ReactNode }) => (
-    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
-      {children}
-    </NuqsTestingAdapter>
-  )
-  const { result } = renderHook(hook, { wrapper })
-  return { result, onUrlUpdate }
+  return renderHookWithNuqs(hook, { searchParams })
 }
 
 // Query param hooks: defaults, parsing, and URL sync behavior.

web/test/nuqs-testing.tsx

@@ -0,0 +1,60 @@
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ComponentProps, ReactElement, ReactNode } from 'react'
+import type { Mock } from 'vitest'
+import { render, renderHook } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { vi } from 'vitest'
+
+type NuqsSearchParams = ComponentProps<typeof NuqsTestingAdapter>['searchParams']
+type NuqsOnUrlUpdate = (event: UrlUpdateEvent) => void
+type NuqsOnUrlUpdateSpy = Mock<NuqsOnUrlUpdate>
+
+type NuqsTestOptions = {
+  searchParams?: NuqsSearchParams
+  onUrlUpdate?: NuqsOnUrlUpdateSpy
+}
+
+type NuqsHookTestOptions<Props> = NuqsTestOptions & {
+  initialProps?: Props
+}
+
+type NuqsWrapperProps = {
+  children: ReactNode
+}
+
+export const createNuqsTestWrapper = (options: NuqsTestOptions = {}) => {
+  const { searchParams = '', onUrlUpdate } = options
+  const urlUpdateSpy = onUrlUpdate ?? vi.fn<NuqsOnUrlUpdate>()
+  const wrapper = ({ children }: NuqsWrapperProps) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={urlUpdateSpy}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+
+  return {
+    wrapper,
+    onUrlUpdate: urlUpdateSpy,
+  }
+}
+
+export const renderWithNuqs = (ui: ReactElement, options: NuqsTestOptions = {}) => {
+  const { wrapper, onUrlUpdate } = createNuqsTestWrapper(options)
+  const rendered = render(ui, { wrapper })
+  return {
+    ...rendered,
+    onUrlUpdate,
+  }
+}
+
+export const renderHookWithNuqs = <Result, Props = void>(
+  callback: (props: Props) => Result,
+  options: NuqsHookTestOptions<Props> = {},
+) => {
+  const { initialProps, ...nuqsOptions } = options
+  const { wrapper, onUrlUpdate } = createNuqsTestWrapper(nuqsOptions)
+  const rendered = renderHook(callback, { wrapper, initialProps })
+  return {
+    ...rendered,
+    onUrlUpdate,
+  }
+}