Skip to content

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

Merged
lyzno1 merged 3 commits into
refactor/datasets-document-list-nuqs-migrationfrom
chore/nuqs-testing-infra-hardening
Feb 16, 2026
Merged

test(web): strengthen nuqs testing infrastructure and documentation#32340
lyzno1 merged 3 commits into
refactor/datasets-document-list-nuqs-migrationfrom
chore/nuqs-testing-infra-hardening

Conversation

@lyzno1

@lyzno1 lyzno1 commented Feb 15, 2026

Copy link
Copy Markdown
Member

Problem

nuqs hooks require an adapter in tests, but our test setup was inconsistent: many specs used ad-hoc wrappers, URL sync assertions were uneven, and docs/skill guidance did not fully encode the same testing model.

Decision

Standardize nuqs testing around one shared helper and align project guidance with that approach.

Model

  • Add web/test/nuqs-testing.tsx as the canonical test utility:
    • createNuqsTestWrapper
    • renderWithNuqs
    • renderHookWithNuqs (including initialProps support)
  • Migrate existing test suites from direct NuqsTestingAdapter usage to shared helpers (apps, datasets, explore, marketplace, tools, context, hooks).
  • Update web/docs/test.md and frontend-testing skill references to require adapter-based URL-state testing and onUrlUpdate assertions.

Impact

  • Removes duplicated wrapper code and prevents adapter-missing failures.
  • Makes URL-state tests more consistent and easier to maintain.
  • Keeps docs/skills aligned with actual test infrastructure, so future tests follow one predictable pattern.

Validation

  • cd web && pnpm type-check:tsgo
  • Targeted Vitest suites for migrated files all pass.

@dosubot dosubot Bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Feb 15, 2026
@github-actions github-actions Bot added the web This relates to changes on the web. label Feb 15, 2026
@dosubot dosubot Bot added the 📚 documentation Improvements or additions to documentation label Feb 15, 2026
@gemini-code-assist

Copy link
Copy Markdown
Contributor

Summary of Changes

Hello @lyzno1, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the testing infrastructure for nuqs (Next.js URL Query State) hooks by introducing a centralized testing utility and updating documentation. The changes aim to standardize test setup, reduce redundant code, and ensure robust validation of URL state synchronization and custom parser behavior, making nuqs related tests more reliable and easier to maintain.

Highlights

  • Shared Testing Utility: Introduced web/test/nuqs-testing.tsx with createNuqsTestWrapper, renderWithNuqs, and renderHookWithNuqs to standardize nuqs query state testing.
  • Test Migration: Migrated several existing tests (create-app-flow.test.tsx, document-management.test.tsx, use-apps-query-state.spec.tsx, use-document-list-query-state.spec.tsx) to utilize the new shared nuqs testing helpers, reducing boilerplate.
  • Documentation Update: Updated web/docs/test.md and agent skill documentation (.agents/skills/frontend-testing/SKILL.md, references/checklist.md, references/mocking.md) with comprehensive guidelines for testing nuqs URL state hooks, including adapter usage, URL synchronization assertions, and custom parser bijection.
  • Standardized Practices: Established best practices for nuqs testing, emphasizing the use of NuqsTestingAdapter via shared helpers, asserting onUrlUpdate events, and handling custom parser edge cases.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog
  • .agents/skills/frontend-testing/SKILL.md
    • Added a new section detailing nuqs query state testing requirements, including adapter usage, URL synchronization assertions, parser bijection, and default-clearing behavior.
  • .agents/skills/frontend-testing/references/checklist.md
    • Appended new checklist items for nuqs URL-state tests, covering NuqsTestingAdapter usage, onUrlUpdate assertions, and custom parser round-trip tests.
  • .agents/skills/frontend-testing/references/mocking.md
    • Introduced a new subsection "2.1 nuqs Query State (Preferred: Testing Adapter)" with an example demonstrating renderHookWithNuqs and guidance on when to mock nuqs directly.
  • web/tests/apps/create-app-flow.test.tsx
    • Replaced direct NuqsTestingAdapter usage with the new renderWithNuqs helper function.
    • Removed NuqsTestingAdapter import.
  • web/tests/datasets/document-management.test.tsx
    • Replaced manual NuqsTestingAdapter setup and onUrlUpdate spy with the renderHookWithNuqs helper.
    • Removed UrlUpdateEvent and ReactNode imports.
  • web/app/components/apps/hooks/tests/use-apps-query-state.spec.tsx
    • Refactored renderWithAdapter to use renderHookWithNuqs, removing boilerplate for NuqsTestingAdapter and onUrlUpdate spy.
    • Removed UrlUpdateEvent and ReactNode imports.
  • web/app/components/datasets/documents/hooks/tests/use-document-list-query-state.spec.tsx
    • Refactored renderWithAdapter to use renderHookWithNuqs, removing boilerplate for NuqsTestingAdapter and onUrlUpdate spy.
    • Removed UrlUpdateEvent and ReactNode imports.
  • web/docs/test.md
    • Added a new section "7.1 nuqs Query State Testing" providing detailed best practices, requirements, and an example for testing nuqs hooks.
  • web/test/nuqs-testing.tsx
    • Added a new file containing shared utility functions: createNuqsTestWrapper for creating a NuqsTestingAdapter wrapper with an onUrlUpdate spy, renderWithNuqs for rendering components, and renderHookWithNuqs for rendering hooks, all simplifying nuqs testing setup.
Activity
  • The pull request includes comprehensive validation steps, demonstrating successful execution of vitest runs for app/components/apps/hooks/__tests__/use-apps-query-state.spec.tsx (20 tests passed), app/components/datasets/documents/hooks/__tests__/use-document-list-query-state.spec.tsx (45 tests passed), __tests__/datasets/document-management.test.tsx (18 tests passed), and __tests__/apps/create-app-flow.test.tsx (16 tests passed).
  • The author provided a detailed summary and rationale for the changes, explaining the need for standardized nuqs testing.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a standardized testing infrastructure for nuqs hooks, which is a great initiative to reduce boilerplate and ensure consistency. The changes include a new shared testing utility, migration of existing tests to use this utility, and comprehensive documentation updates. My review focuses on improving the new utility and ensuring consistency in the documentation examples. Overall, this is a solid improvement for the project's testing practices.

Comment thread .agents/skills/frontend-testing/references/mocking.md
Comment thread web/test/nuqs-testing.tsx Outdated
@lyzno1
lyzno1 merged commit b27b346 into refactor/datasets-document-list-nuqs-migration Feb 16, 2026
2 checks passed
@lyzno1
lyzno1 deleted the chore/nuqs-testing-infra-hardening branch February 16, 2026 04:21

// Render helper wrapping with NuqsTestingAdapter
// Render helper wrapping with shared nuqs testing helper.
const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

onUrlUpdate is created at the top level of the module and shared across all tests. However, there is no beforeEach(() => onUrlUpdate.mockClear()) to reset it, which could lead to state leakage between tests.

default: () => <div data-testid="search-box-wrapper">SearchBoxWrapper</div>,
}))

const { wrapper: NuqsWrapper } = createNuqsTestWrapper()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same thing. it would be better to create in beforeEach

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

📚 documentation Improvements or additions to documentation size:L This PR changes 100-499 lines, ignoring generated files. web This relates to changes on the web.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants