DEV Community: a-dev

React Hook to Manage URL Search Params:?mess=less

a-dev — Mon, 03 Feb 2025 16:16:54 +0000

Keeping your page state in sync with URL search params doesn't seem like a big deal (it's definitely not cache invalidation). However, it becomes painful when you have multiple parameters, validation logic, and interdependencies 🙄 between parameters. I once faced this obstacle and created a hook that helped me to solve the problem. And now I want to share it with you. Yes, it's a React hook, yet the idea and DX can be adapted to other frameworks.

Before, I have to say that my react-hook is not a silver bullet. There are couple libraries that you can use, and I admit that they can suit your needs better. I recommend you to check them out:

nuqs - literally state manager for search params. If you want to put JSON in search params, this is your choice. It offers adapters for Next.js, React Router. And documentation is awesome.
tanstack router - not 'just lib', I know. But it's really great and I like that they saw the problem of search params and did some good stuff around it.

The demo

You can click buttons and enter text in the input field here (ignore the decorative landing page — I just had some fun with v0). Notice how the URL changes. If you refresh the page, the state is restored from the URL.
Also, check out the code on GitHub, especially the hook itself.

DX

First, create a Zod schema for the URL search parameters. Suppose you have a catalog page for clothes with filtering and pagination; a basic version of the schema might look like this:

const schema = z
  .object({
    page: z.string().default('1'),
    type: z.enum(['t-shirt', 'jeans', 'jacket']).default('t-shirt'),
    brand: z.array(z.string()).optional(),
    from: z.string().optional(),
    to: z.string().optional(),
  })

type Schema = z.infer<typeof schema>;

Notice, I've added default values for the page and type parameters — it isn't the best practice (more caveats will be discussed later), but it serves well for an example. This means that even if a user visits the page without any search parameters in the URL, the hook will add them to the address. For instance, if you go to this demo link without a query, you will still see ?page=1 in the address bar.

I strictly recommend you add parameters to the link on the page, it helps to avoid unnecessary renders and redirects. But sometimes it's not easy and this small hack could be useful.

The second business logic action that you find in this type filters, is 'dependent changes' — when one parameter changes, another should be changed too. For example, if you change the type to 't-shirt', the brand should be reset to default. It's a common case, and that really why I created this hook.

const beforeUpdateCallback: BeforeUpdateCallback<Schema> = (updatedParams) => {
  if (Object.keys(updatedParams).includes('page')) {
    /*
     * If the user is paginating,
     * leave the rest of the search parameters unchanged.
     */
    return updatedParams;
  }

  if (Object.keys(updatedParams).some((key) => ['type'].includes(key))) {
    /*
     * When the user changes the clothes type,
     * the brand filter should be reset.
     */
    return {
      page: '1',
      brand: [],
      ...updatedParams,
    };
  }

  /*
  * For any other changes, we simply reset pagination to the first page.
  */
  return {
    page: '1',
    ...updatedParams,
  };
};

This callback enhances the user experience by automatically resetting filters and preventing users from landing on non-existent pages when they change the 'type' filter.

The last step is to create and export the hooks:

const {
  URLSearchParamsProvider: ClothesFilterProvider,
  useUpdateURLSearchParams: useUpdateClothesFilter,
  useGetURLSearchParams: useGetClothesFilter,
} = createUrlSearchParams<Schema>({
  zodSchema,
  beforeUpdateCallback,
});

export { ClothesFilterProvider, useUpdateClothesFilter, useGetClothesFilter };

Type note: don't forget to add types of schema. One of the coolest feature is types for your search params.

UX Note: Make sure to debounce your form state updates. If you run the demo locally, you can simulate a longer data-loading time by changing the delay in the clientLoader (for example, set it to 1000ms). It shows how a sluggish search input can feel without proper debouncing

Implementation

Just wrap your clothes page component with ClothesFilterProvider and use the hooks to get and update search params. Here's how:

<ClothesFilterProvider>
  <ClothesPage />
</ClothesFilterProvider>

const ClothesPage: FC = () => {
  const { page, type, brand, from, to } = useGetClothesFilter ();
  const updateFilter = useUpdateClothesFilter();

  return (
    <div>
      <button onClick={() => updateFilter({ page: '2' })}>Go to page 2</button>
      <button onClick={() => updateFilter({ type: 'jeans' })}>Show jeans</button>
      <button onClick={() => updateFilter({ brand: ['nike', 'adidas'] })}>Show Nike and Adidas</button>
      {/* and so on */}
    </div>
  );
};

As you can see, working with arrays in this hook is straightforward. Remember to properly handle array changes, such as filtering when removing items and preserving existing selections. Check out the demo for practical example.

How it's done

Pretty simple. You need methods for encoding and decoding search parameters, some logic for handling array parameters, and a method for updating parameters that will call the callback before any actions. That's it.

One important addition I made but never used is default parameters that can modify the URL on the page loading. For it I use the React useLayoutEffect hook to prevent unnecessary renders. However, as mentioned earlier, I don't consider it as the best practice.

Look more closely at the source code and docs (ai gen) and feel free to ask questions.

In this version, the hook uses react-router v7 (though nothing has changed for v6). I haven’t tried it with Next.js yet, but I suppose it will work if the search-params methods are updated accordingly.

Library?

For now, I do not plan to publish this hook as a library. However, if you think it should be... let me know in comments.

Good luck! 🚀

Testing with Playwright: Use i18next Translations in Tests, but not `t('key')`

a-dev — Sun, 05 Jan 2025 18:23:11 +0000

E2E-testing localized applications can be challenging, translations keys can make test code harder to read and maintain. This article demonstrates how to test i18next translations in React app using Playwright, with a simplified approach that avoids translation keys. The idea can be used in any project with i18next or similar libraries.

This approach builds upon concepts from my previous article about using Playwright fixtures for authorization in RBAC applications (Testing with Playwright: Making Authorization Less Painful and More Readable).

Here's a practical example of how it looks in a test:

const LOCALES = ["en", "es", "zh"];

describe("Author page", () => {
  for (let locale of LOCALES) {
    test(`it has a link to articles. {locale: ${locale}}`, async ({ page, tkey }) => {
      await page.goto("/authors/123");
      const link = await page.getByRole("link").nth(0).textContent();
      expect(link).toBe(tkey("Mis articulos", "menu"));
    });
  }
});

The key concept here is using the actual phrase instead of an i18n key for translation. Traditional approaches often use translation keys, which can be hard to read. For example: expect(link).toBe(t("menu.current_user_articles_link"));. This contradicts the principle of writing easily readable tests.

Implementation: Swapping Translation Keys with Phrases

The implementation revolves around using phrases that correspond to translation keys in tests. Here's an example of a typical translation file:

{
  "en": {
    "menu": {
      "current_user_articles_link": "My articles"
    }
  },
  "es": {
    "menu": {
      "current_user_articles_link": "Mis articulos"
    }
  },
  "zh": {
    "menu": {
      "current_user_articles_link": "我的文章"
    }
  }
}

We'll transform this into a swapped JSON format where phrases map to their corresponding keys (using Spanish as the primary language in this example):

{
  "Mis articulos": "menu.current_user_articles_link"
}

To achieve this transformation, we'll create a utility function that swaps keys and values in the JSON files. Here's the implementation using TypeScript and Deno:

import { readdir, readFile, writeFile } from 'node:fs/promises';
import { join } from 'node:path';

const CONSTANTS = {
  DIRECTORY_PATH: 'app/public/locale/es', // Path to locale language files
  SWAPPED_FILE_PATH: 'e2e/fixtures/i18n/es_swapped.json', // Output path for swapped JSON
  FILE_ENCODING: 'utf8',
} as const;

interface TranslationObject {
  [key: string]: string | TranslationObject;
}
type SwappedTranslations = Record<string, Record<string, string>>;

function swapKeysAndValues(obj: TranslationObject): Record<string, string> {
  const swappedObject: Record<string, string> = {};

  function traverseObj(value: unknown, path = ''): void {
    if (value && typeof value === 'object') {
      for (const [key, val] of Object.entries(value)) {
        traverseObj(val, path ? `${path}.${key}` : key);
      }
    } else if (typeof value === 'string') {
      swappedObject[value] = path;
    }
  }

  traverseObj(obj);
  return swappedObject;
}

const JSON_EXTENSION_REGEX = /\.json$/;

async function buildJsonWithNamespaces(): Promise<void> {
  try {
    const files = await readdir(CONSTANTS.DIRECTORY_PATH);
    const result: SwappedTranslations = {};

    for (const file of files) {
      const filePath = join(CONSTANTS.DIRECTORY_PATH, file);
      const fileContent = await readFile(filePath, CONSTANTS.FILE_ENCODING);
      const parsedFileContent = JSON.parse(fileContent) as TranslationObject;
      const swappedContent = swapKeysAndValues(parsedFileContent);
      const key = file.replace(JSON_EXTENSION_REGEX, '');

      result[key] = swappedContent;
    }

    await writeFile(
      CONSTANTS.SWAPPED_FILE_PATH,
      JSON.stringify(result, null, 2),
      CONSTANTS.FILE_ENCODING,
    );

    console.info('✅ Successfully generated swapped translations');
  } catch (error) {
    console.error(
      '❌ Failed to generate swapped translations:',
      error instanceof Error ? error.message : error,
    );
    process.exit(1);
  }
}

console.info('🔄 Converting locale to swapped JSON...');
buildJsonWithNamespaces();

Run this script using: deno run --allow-read --allow-write path_to_swap.ts

Setting Up i18n for Playwright

Now let's create a fixture for i18n in Playwright. This implementation is inspired by the playwright-i18next-fixture library, but with custom modifications for better control:

import * as fs from "node:fs";
import path from "node:path";
import Backend from "i18next-http-backend";
import { initReactI18next } from "react-i18next";
import { test as base } from "@playwright/test";
import { createInstance, type i18n, type TFunction } from "i18next";

const CONFIG = {
  TRANSLATIONS_PATH: "translations_path_to_files/or_api_endpoint",
  SWAPPED_TRANSLATIONS_PATH: "e2e/fixtures/i18n/es_swapped.json",
  LOCAL_STORAGE_KEY: "locale",
  SUPPORTED_LANGUAGES: ["es", "en", "zh"] as const,
  DEFAULT_LANGUAGE: "es",
  NAMESPACES: ["shared", "menu"] as const,
  DEFAULT_NS: "shared",
} as const;

const data = fs.existsSync(CONFIG.SWAPPED_TRANSLATIONS_PATH)
  ? JSON.parse(fs.readFileSync(CONFIG.SWAPPED_TRANSLATIONS_PATH, "utf8"))
  : {};

export function findTranslationByKey(
  key: string,
  namespace: string,
): string | undefined {
  const value = data[namespace][key];
  if (value && typeof value === "string") return value;

  throw new Error(
    `🔴 Translation not found for the namespace "${namespace}" and key "${key}"`,
  );
}

type SupportedLanguage = (typeof CONFIG.SUPPORTED_LANGUAGES)[number];
type Namespace = (typeof CONFIG.NAMESPACES)[number];

export const i18nOptions = {
  plugins: [Backend, initReactI18next],
  options: {
    lng: CONFIG.DEFAULT_LANGUAGE,
    load: "languageOnly",
    ns: CONFIG.NAMESPACES,
    defaultNS: CONFIG.DEFAULT_NS,
    supportedLngs: CONFIG.SUPPORTED_LANGUAGES,
    backend: {
      allowMultiLoading: true,
      loadPath: CONFIG.TRANSLATIONS_PATH,
    },
    react: {
      useSuspense: true,
    },
  },
} as const;

let storedI18n: i18n | undefined;

async function initI18n({
  plugins,
  options,
}: typeof i18nOptions): Promise<i18n> {
  if (!storedI18n?.isInitialized) {
    const i18n = plugins.reduce(
      (i18n, plugin) => i18n.use(plugin),
      createInstance(),
    );
    await i18n.init(options);
    storedI18n = i18n;
    return i18n;
  }
  return storedI18n;
}

export type Tkey = (key: string, namespace?: Namespace) => string;

interface I18nFixtures {
  i18n: i18n;
  t: TFunction;
  tkey: Tkey;
}

/*
  Fixture for i18n functionality. 
  It initializes the i18next instance and checks the language setting
  in the storageState created by Playwright. 
  Similar technique was used in my RBAC example.
  For more details, see my article about authorization testing 
  (https://dev.to/a-dev/testing-with-playwright-how-to-make-authorization-less-painful-and-more-readable-3344)
  and the official Playwright documentation
  (https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
*/

export const i18nFixture = base.extend<I18nFixtures>({
  i18n: async ({ storageState }, use) => {
    const i18nInstance = await initI18n(i18nOptions);

    if (storageState) {
      try {
        const data = JSON.parse(
          fs.readFileSync(path.resolve(storageState as string), "utf8"),
        );

        // This example uses localStorage to set the language.
        const localStorage = data?.origins?.[0]?.localStorage;
        const language = localStorage?.find(
          (i) => i.name === CONFIG.LOCAL_STORAGE_KEY,
        )?.value as SupportedLanguage | undefined;

        if (!language) {
          throw new Error(
            `No language setting found in localStorage (key: ${CONFIG.LOCAL_STORAGE_KEY})`,
          );
        }

        if (!CONFIG.SUPPORTED_LANGUAGES.includes(language)) {
          throw new Error(
            `Unsupported language: ${language}. Supported languages: ${CONFIG.SUPPORTED_LANGUAGES.join(", ")}`,
          );
        }

        // Change language if different from current
        if (i18nInstance.language !== language) {
          await i18nInstance.changeLanguage(language);
        }
      } catch (error) {
        throw new Error(`Failed to process storage state: ${error.message}`);
      }
    }

    await use(i18nInstance);
  },
  tkey: async ({ t }, use) => {
    await use((str?: string, namespace = "shared"): string => {
      if (!str) return "⭕ Error: no translation";
      const tkey = findTranslationByKey(str, namespace);
      return t(`${namespace}:${tkey}`);
    });
  },
  t: async ({ i18n }, use) => {
  // The same t function for usual translation keys
    await use(i18n.t);
  },
});

Finally, we can use the i18nFixture in our Playwright tests to handle translations and language settings. To learn more about working with fixtures, check out the official Playwright documentation. I recommend creating an index.ts file that exports all fixtures, which can then be imported into your test files.

import { mergeTests } from '@playwright/test';
import { i18nFixture } from './fixtures/i18n';

const test = mergeTests({
  ...i18nFixture,
});

export { test };

Wish you happy testing with Playwright and i18next! 🚀
If you have any questions or suggestions don't hesitate to comment below.

Testing with Playwright: How to Make Authentication Less Painful and More Readable

a-dev — Mon, 09 Sep 2024 18:11:53 +0000

Playwright is a great tool for e2e-tests and more (we'll discuss this another time). It's easy to write tests for what your website displays, but it becomes much harder when you want to test what your application actually does. Especially when users take many steps to achieve their goals - your tests can grow exponentially, with a thousand lines not being uncommon.

This is where abstractions become necessary. Developers start to use POMs (Page Object Models) and custom fixtures. We'll talk about POMs another time (again), for now, I want to tell you how to create a very handy fixture.

Most complex apps have an authentication level (who is this user?) and an authorization level (what can this user do?). In most cases, this is built with role models (RBAC). It's great if you can test your app features with different users/roles.

You can read about the core concept of authentication in the official docs (which I highly recommend). These solutions are great for cases with one authorization level (e.g., admin), but become verbose when you want to change users in different tests or, for example, run one test (not a whole bunch of tests) for five different roles simultaneously.

Look at what the test might look like after we create this fixture:

// admin
test('that {role: admin} can delete any article', async () => {
  //...
});

// more roles
const ROLES = ['admin', 'owner', 'manager', 'guest'] as const;

for (const role of ROLES) {
  test(`that {role: ${role}} can buy a coffee`, async () => {
    //...
  });
}

// specific user
test('that {email: user-email@example.com} can do whatever they want', async () => {
  //...
});

Looks great, doesn't it?

User-roles database

When I started struggling with multiple roles and different business logic expectations in e2e tests, I realized that a simple object defining users, their roles, and other necessary data would be ideal.
The shape of this object isn't crucial, you can create it as you see fit and then add an algorithm to extract data from it.

type Roles = 'admin' | 'owner' | 'manager' | 'guest';
type TestUsersData = {
  [key in Roles]: {
    email: string;
    password?: string; // Don't store real passwords here.
    // These email/password credentials should be created
    // for test purposes only in a test or dev environment/DB
    data: {
      // This isn't used in authorization,
      // but can be useful in tests
      name: string;
      status?: string;
    }
  };
}

const testUsersData: TestUsersData = {
  admin: {
    email: 'admin@example.com',
    password: 'admin',
    data: {
      name: 'Admin',
      status: 'active'
    }
  },
  owner: {
    email: 'owner@example.com',
    password: 'owner',
    data: {
      name: 'Owner',
      status: 'active'
    }
  },
// ... and so on

I've created a simple function to get user data by role, which returns user credentials for authorization:

import { testUsersData } from './test-users-data';

export function defineTestUser({ role, email, password }: Props) {
  if (!(role || email)) return;

  return {
    email: email ?? (role ? testUsersData[role]?.email : undefined),
    password: password ?? 'default-password', // default password
  };
}

The next important step is to create a method that parses data between curly braces from the test title and returns the data:

export function parseDataFromTestTitle(str: string): Record<string, string> {
  // Match all content between curly braces
  const regex = /{([\s\S]*?)}/g;
  const matches = str.match(regex) || [];

  const combinedObject: Record<string, string> = {};

  // Iterate through each matched set of curly braces
  for (const match of matches) {
    // Remove curly braces and split by comma 
    // to get individual key-value pairs
    const keyValuePairs = match.slice(1, -1).split(',');

    for (const pair of keyValuePairs) {
      // Split by colon and trim whitespace to separate key and value
      const [key, value] = pair.split(':').map((part) => part.trim());

      if (key && value) {
        combinedObject[key] = value;
      }
    }
  }

  return combinedObject;
}

As you can see, the idea is simple: you define a user in the test title, and then you can use this data in the fixture to authenticate.

Fixture

Before we create a fixture, we need to create a helper function to authenticate the user.
In my case, I use a JWT token, so I have a function to get a token by user credentials. For cookie-based authorization, the helper will be even simpler.

import { expect, type Page } from '@playwright/test';

export async function authenticateUser({ page, user }: {page: Page, user: UserType}) {
  // Get favicon - this is a small hack to ensure that Playwright
  // opens the browser and is ready to load the page.
  // You can use any other address, but it should load quickly.
  await page.goto('/favicon.ico');


  // Send a POST request to your backend server for authentication
  const response = await page.request.post('your_backend_api_endpoint/login', {
    data: { user },
    timeout: 30000,
  });

 // Handle errors
  if (response.status() === 401) {
    throw new Error(`🔴 Wrong credentials. Check role, email, or password: ${JSON.stringify(response)}`);
  } else if (!response.ok()) {
    throw new Error(`🔴 Failed to authenticate user. Status: ${response.status()}`);
  }

  // Ensure the response is successful
  expect(response.ok()).toBeTruthy();

  // Extract the authorization token from the response headers
  const token = response.headers().authorization;
  await page.evaluate(
    (token: string) => {
      if (!token) {
        throw new Error('No token received from the server');
      }

      // window.localStorage is used to store the JWT token
      localStorage.setItem('jwt', JSON.stringify(token));
    },
    token,
  );

  return { page };
}

And now (finally!) we can create a fixture.

import { test as base } from '@playwright/test';
import path from 'node:path';
import * as fs from 'node:fs';
// don't forget to import authenticateUser, parseDataFromTestTitle and defineTestUser functions

const authenticateUserFixture = base.extend<{ workerStorageState: string | undefined }>({
  storageState: async ({ workerStorageState }, use) => use(workerStorageState),
  workerStorageState: [
    async ({ browser }, use, testInfo) => {
      // Construct the test title path string and get string
      // from test title and title of parent test.describe
      const allPathString = [
        test.info().titlePath.reverse().join(' + '),
        test.info().title,
      ].join(' + ');
      const dataParsedFromTitle = parseDataFromTestTitle(allPathString);
      const user = defineTestUser(dataParsedFromTitle);
      console.info('🍏 parsed user credentials', user);
      if (!user) {
        await use(undefined);
        return;
      }

      // Define the file path for storing authentication state
      const fileName = path.resolve(
        testInfo.project.outputDir,
        `.auth/${user.email}.json`,
      );

      // Check if the authentication state file exists
      // and is fresh (less than 5 minutes old)
      const stats = fs.existsSync(fileName) ? fs.statSync(fileName) : null;
      if (stats && stats.mtimeMs > new Date().getTime() - 5 * 60 * 1000) {
        const origins = JSON.parse(fs.readFileSync(fileName, 'utf-8'))
          ?.origins[0];

        // And again, here I check JWT token in localStorage,
        // but you can check cookies or any other data
        const localStorage = origins?.localStorage;
        const hasJWTToken = Boolean(
          localStorage?.find((i: Record<string, string>) => i.name === 'jwt')
            ?.value,
        );
        if (origins?.origin === testInfo.project.use.baseURL && hasJWTToken) {
          console.info('🟡 Sign in skipped because token is fresh');
          await use(fileName);
          return;
        }
      }

      // Create a new browser page for authentication
      const page = await browser.newPage({
        storageState: undefined,
        baseURL: testInfo.project.use.baseURL,
      });

      // Authenticate the user and save the storage state
      await authenticateUser({ page, user, locale });
      await page.context().storageState({ path: fileName });
      console.info('[test authentication] 👤 📧', user?.email, locale);
      await page.close();

      await use(fileName);
    },

    // You can use {scope: 'worker'} here, but in this case, 
    // authentication will depend on the worker, 
    // which could be faster but can make it harder 
    // to write tests where credentials change
    { scope: 'test' },
  ],
});

Now you can use this fixture in your tests.
I have many fixtures in my project, so I have a helper function to use them. You can read more about this in the official docs.

// tests/index.ts or wherever you have your tests
import { mergeTests } from '@playwright/test';
import { authenticateUserFixture } from './fixtures/authenticate-user-fixture';

const test = mergeTests(
  authenticateUserFixture,
  // ... other fixtures
)

export { test };

This approach offers several advantages:

Test titles clearly indicate which user or role is being tested.
You can easily test different user roles or specific users without modifying the test code.
The fixture reuses authentication tokens when possible, speeding up test execution.
User credentials and authentication logic are centralized, making updates easier.

By implementing this system, you can significantly reduce the complexity of managing different user roles in your Playwright tests.

Remember, the specific implementation may vary based on your authentication mechanism (JWT, cookies, etc.), but the core concept remains the same. Adapt this approach to fit your project's needs, and enjoy! 🚀

Bonus

I encountered a specific test scenario where I needed to change role in the middle of the test. To address this, I created the 'useUser' fixture.
This fixture differs slightly from the previous one — you don't need to store authentication data in a file, as it operates only within the scope of the test.

export const authenticateUserInContextFixture = base.extend<UseUser, { storageState: string }>({
  useUser: [
    async ({ browser, storageState }, use, workerInfo) => {
      await use(async (userData, options) => {
        const user = defineTestUser(userData);
        if (!user)
          throw Error('🔴 Wrong credentials. Check role, email or password');

        const newContext = await browser.newContext({
          storageState: undefined,
          baseURL: workerInfo.project.use.baseURL,
        });
        const page = await newContext.newPage();
        await authenticateUser({ page, user });
        console.info('[browser-context] 👤 📧', user?.email);

        return page;
      });
    },
    { scope: 'test' },
  ],
});

Don't forget to add this fixture to your tests:

const test = mergeTests(
  authenticateUserFixture,
  authenticateUserInContextFixture,
  // ... other fixtures
)

Now you can use it in your tests.
In this example, I have two contexts within one test: one for a user with the 'reader' role and another for a user with the 'admin' role. The reader can only create comments and cannot delete them, while the admin can delete comments.

import { test } from 'tests/index.ts';

test('useUser fixture in the middle of the test. Start with {role: reader}', async ({
  useUser,
  page,
}) => {
  await page.goto('/articles/1');
  // ... add comment to the article. 
  // Use page.click, page.fill, etc.

  const adminPage = await useUser({ role: 'admin' });
  await adminPage.goto('/articles/1');
  // ... delete comment. 
  // Use adminPage.click, adminPage.fill, etc.

  // You can close the admin user's page if you don't need it anymore
  await adminPage.close();

  // get updated data with reader
  await page.reload({ waitUntil: 'domcontentloaded' });
  // ... check that comment isn't here
});

If you run Playwright with the option to open the browser, you'll see two browser windows: one for the reader and another for the admin. This is particularly useful when you need to test different roles within a single test.