docs: Update Jest examples (#1797)

Somehow the Jest examples in this repo still worked, but if you try to
use `next-intl` outside of this monorepo there was an issue with Jest.
The problem is that Jest doesn't support ESM (see e.g.
vercel/next.js#40183).

Ref #1796

Author: amannn

docs/src/pages/blog/next-intl-4-0.mdx

@@ -188,6 +188,8 @@ The build output of `next-intl` has been modernized and now leverages the follow
 2. **Modern JSX transform:** The peer dependency for React has been bumped to v17 in order to use the more efficient, modern JSX transform.
 3. **Modern syntax:** Syntax is now compiled down to the Browserslist `defaults` query, which is a shortcut for ">0.5%, last 2 versions, Firefox ESR, not dead"—a baseline that is considered a reasonable target for modern apps.
 
+If you're using `next-intl` with Jest or Vitest, please also refer to the new [testing docs](/docs/environments/testing).
+
 With these changes, the bundle size of `next-intl` has been reduced by ~7% ([PR #1470](https://github.com/amannn/next-intl/pull/1470)).
 
 ## Improved inheritance of `NextIntlClientProvider` [#nextintlclientprovider-inheritance]

docs/src/pages/docs/environments/_meta.tsx

@@ -5,5 +5,6 @@ export default {
   'error-files': 'Error files (e.g. not-found)',
   mdx: 'Markdown (MDX)',
   'core-library': 'Core library',
-  'runtime-requirements': 'Runtime requirements'
+  'runtime-requirements': 'Runtime requirements',
+  testing: 'Testing'
 };

docs/src/pages/docs/environments/testing.mdx

@@ -0,0 +1,64 @@
+import Callout from '@/components/Callout';
+import Details from '@/components/Details';
+
+# Testing
+
+Components that use `next-intl` can be used in unit tests:
+
+```tsx
+import {render} from '@testing-library/react';
+import {NextIntlClientProvider} from 'next-intl';
+import {expect, it} from 'vitest';
+import messages from '../../messages/en.json';
+import UserProfile from './UserProfile';
+
+it('renders', () => {
+  render(
+    <NextIntlClientProvider locale="en" messages={messages}>
+      <UserProfile />
+    </NextIntlClientProvider>
+  );
+});
+```
+
+To avoid having to mock server components, it can be beneficial to define components as [non-async functions](/docs/environments/server-client-components#async-or-non-async), allowing you to flexibly render them in any environment.
+
+## Vitest
+
+`next-intl` is bundled as ESM-only, which requires the usage of [explicit file extensions](https://nodejs.org/api/esm.html#mandatory-file-extensions) internally. However, in order to avoid a [deoptimization in Next.js](https://github.com/vercel/next.js/issues/77200), `next-intl` currently has to import from `next/navigation` instead of `next/navigation.js`.
+
+Vitest correctly assumes a file extension though, therefore for the time being, if you're using [`createNavigation`](/docs/routing/navigation), you need to ask Vitest to process imports within `next-intl`:
+
+```tsx
+import {defineConfig} from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    server: {
+      deps: {
+        // https://github.com/vercel/next.js/issues/77200
+        inline: ['next-intl']
+      }
+    }
+  }
+});
+```
+
+## Jest
+
+Since Jest doesn't have built-in ESM support, you need to instruct Jest to transform imports from `next-intl`:
+
+```tsx
+const nextJest = require('next/jest');
+
+const createJestConfig = nextJest({dir: './'});
+
+module.exports = async () => ({
+  ...(await createJestConfig({
+    testEnvironment: 'jsdom',
+    rootDir: 'src'
+  })()),
+  // https://github.com/vercel/next.js/issues/40183
+  transformIgnorePatterns: ['node_modules/(?!next-intl)/']
+});
+```

examples/example-app-router-playground/jest.config.js

@@ -3,11 +3,10 @@ const nextJest = require('next/jest');
 
 const createJestConfig = nextJest({dir: './'});
 
-module.exports = createJestConfig({
-  moduleNameMapper: {
-    '^next$': require.resolve('next'),
-    '^next/navigation$': require.resolve('next/navigation')
-  },
-  testEnvironment: 'jsdom',
-  rootDir: 'src'
+module.exports = async () => ({
+  ...(await createJestConfig({
+    testEnvironment: 'jsdom',
+    rootDir: 'src'
+  })()),
+  transformIgnorePatterns: ['node_modules/(?!next-intl)/']
 });

examples/example-app-router/jest.config.js

@@ -3,11 +3,10 @@ const nextJest = require('next/jest');
 
 const createJestConfig = nextJest({dir: './'});
 
-module.exports = createJestConfig({
-  moduleNameMapper: {
-    '^next$': require.resolve('next'),
-    '^next/navigation$': require.resolve('next/navigation')
-  },
-  testEnvironment: 'jsdom',
-  rootDir: 'src'
+module.exports = async () => ({
+  ...(await createJestConfig({
+    testEnvironment: 'jsdom',
+    rootDir: 'src'
+  })()),
+  transformIgnorePatterns: ['node_modules/(?!next-intl)/']
 });

examples/example-pages-router-advanced/jest.config.js

@@ -3,7 +3,10 @@ const nextJest = require('next/jest');
 
 const createJestConfig = nextJest({dir: './'});
 
-module.exports = createJestConfig({
-  testEnvironment: 'jsdom',
-  rootDir: 'src'
+module.exports = async () => ({
+  ...(await createJestConfig({
+    testEnvironment: 'jsdom',
+    rootDir: 'src'
+  })()),
+  transformIgnorePatterns: ['node_modules/(?!next-intl)/']
 });