Testing

Since nuqs 2, you can unit-test components that use useQueryState(s) hooks by wrapping your rendered component in a NuqsTestingAdapter, or using the withNuqsTestingAdapter higher-order component.

With Vitest

Here is an example for Vitest and Testing Library to test a button rendering a counter:

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { withNuqsTestingAdapter, type UrlUpdateEvent } from 'nuqs/adapters/testing'
import { describe, expect, it, vi } from 'vitest'
import { CounterButton } from './counter-button'
 
it('should increment the count when clicked', async () => {
  const user = userEvent.setup()
  const onUrlUpdate = vi.fn<[UrlUpdateEvent]>()
  render(<CounterButton />, {
    // 1. Setup the test by passing initial search params / querystring:
    wrapper: withNuqsTestingAdapter({ searchParams: '?count=42', onUrlUpdate })
  })
  // 2. Act
  const button = screen.getByRole('button')
  await user.click(button)
  // 3. Assert changes in the state and in the (mocked) URL
  expect(button).toHaveTextContent('count is 43')
  expect(onUrlUpdate).toHaveBeenCalledOnce()
  const event = onUrlUpdate.mock.calls[0][0]!
  expect(event.queryString).toBe('?count=43')
  expect(event.searchParams.get('count')).toBe('43')
  expect(event.options.history).toBe('push')
})

See issue #259 for more testing-related discussions.

With Jest

Since nuqs 2 is an ESM-only package, there are a few hoops you need to jump through to make it work with Jest. This is extracted from the Jest ESM guide.

1. Add the following options to your jest.config.ts file:

const config: Config = {
  // <Other options here>

  extensionsToTreatAsEsm: [".ts", ".tsx"],
  transform: {}
};

2. Change your test command to include the --experimental-vm-modules flag:

{
  "scripts": {
    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" jest"
  }
}

NuqsTestingAdapter

The withNuqsTestingAdapter function is a higher-order component that wraps your component with a NuqsTestingAdapter, but you can also use it directly.

It takes the following props:

• searchParams: The initial search params to use for the test. These can be a query string, a URLSearchParams object or a record object with string values.

import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 
<NuqsTestingAdapter searchParams="?q=hello&limit=10">
<NuqsTestingAdapter searchParams={new URLSearchParams("?q=hello&limit=10")}>
<NuqsTestingAdapter searchParams={{
  q: 'hello',
  limit: '10' // Values are serialized strings
}}>

• onUrlUpdate, a function that will be called when the URL is updated by the component. It receives an object with:
  • the new search params as an instance of URLSearchParams
  • the new querystring (for convenience)
  • the options used to update the URL.