Forem: gcascio

Typed E2E test IDs

gcascio — Wed, 01 May 2024 17:18:08 +0000

tl;dr - Improving the DX when writing E2E tests by using typed test IDs.

Utilizing TypeScript to create typed test IDs

Sharing test IDs between the frontend and the test suite:
// app/page.tsx
<h1 {...e2e.home_heading}>
  Welcome
</h1>

// tests/home.spec.ts
const heading = page.getByTestId(e2e.home_heading.id);
Full example

When writing E2E tests, it is common to use test IDs to select elements on the page. This is especially useful when the element does not have a unique selector or when the selector is likely to change. However, hardcoding test IDs in place can lead to errors and make the test suite harder to maintain. In this post, I will present a pattern that allows you to share test IDs between the frontend and the test suite, and how to utilize TypeScript to create typed test IDs.

We start with a project that was bootstrapped with npx create-next-app. For the E2E test we use Playwright and set it up as described in the testing guide provided by Next.js.

Getting started

We start by simplifying the bootstrapped Next.js project, so that we have a single page left:

// app/page.tsx
export default function Home() {
  return (
    <main>
      <h1>
        Welcome
      </h1>
    </main>
  );
}

and write a simple E2E test for it:

// tests/home.spec.ts
import { test, expect } from '@playwright/test';

test('has heading', async ({ page }) => {
  await page.goto('/');

  const heading = page.locator('h1');

  await expect(heading).toBeVisible();
});

This test is straightforward and checks if the heading is visible. The selector ('h1') for the heading is as simple as it gets but in a real-world application it is likely that we need to select elements in a more reliable way.

We can start by adding a test ID to the heading:

// app/page.tsx
<h1 data-testid="home_heading">
  Welcome
</h1>

and update the test to use the test ID:

// tests/home.spec.ts
const heading = page.getByTestId('home_heading');

This is a huge improvement. The structure of the page can change now without breaking the test.

A straight forward approach

We can take the previous approach a step further by sharing the test ID between the frontend and the test suite. For this we create a file e2e.ts and define a object containing the test IDs:

// utils/e2e.ts
const e2e = {
  homeHeading: 'home_heading',
};

and import the test IDs in the page and in the test:

// app/page.tsx
import { e2e } from '../utils/e2e';

<h1 data-testid={e2e.homeHeading}>
  Welcome
</h1>

// tests/home.spec.ts
import { e2e } from '../utils/e2e';

const heading = page.getByTestId(e2e.homeHeading);

This alone already improves the DX and the maintainability of the test suite as we now have a single source of truth for the test IDs. The only thing we would have to remember when using this approach is the name of the data attribute data-testid and it would be nice if this is not the case.

Typed test IDs

Instead of setting the data attribute directly we could also pass it by spreading a corresponding object, for instance:

const testId = { 'data-testid': 'home_heading' };

// app/page.tsx
<h1 {...testId} >
  Welcome
</h1>

Now, extending on that idea we can improve our previously defined e2e object:

// utils/e2e.ts
const dataAttribute = 'data-testid' as const;
const attributes = ['home_heading'] as const;

class Attribute<T extends string> {
  [dataAttribute]: T;

  constructor(value: T) {
    this[dataAttribute] = value;
  }

  get id() {
    return this[dataAttribute];
  }
}

type Mapped<T extends string> = {
  [K in T]: Attribute<K>;
};

type E2EAttributes = Mapped<typeof attributes[number]>;

export const e2e = Object.fromEntries(
  attributes.map((attribute) => [attribute, new Attribute(attribute)]),
) as E2EAttributes;

Breaking it down, we define a dataAttribute and an array of attributes in a single location. Each attribute is then mapped to an Attribute class which enables us to spread the test ID in a component and, at the same time, comfortably access the test ID in the test suite. With the use of this approach our final test setup looks like this:

// app/page.tsx
import { e2e } from '../utils/e2e';

<h1 {...e2e.home_heading}>
  Welcome
</h1>

// tests/home.spec.ts
import { e2e } from '../utils/e2e';

const heading = page.getByTestId(e2e.home_heading.id);

Noteworthy is that we can safely spread the Attribute object in the component since spread only copies enumerable own properties, this means the id getter will have no effect on the component.

Dynamic breadcrumbs in Next.js using the app router

gcascio — Mon, 01 Apr 2024 20:20:15 +0000

Often, breadcrumbs are used to show the user's current location within the site hierarchy. In a static site, breadcrumbs are typically hard-coded into the page. However, in a dynamic site, breadcrumbs need to be generated based on the current path. Additionally, sometimes one needs to set breadcrumbs asynchronously, such as when fetching data from an API. In this post, I'll demonstrate one of many ways to
implement dynamic breadcrumbs in Next.js when using the app router.

Getting started

We start by creating a new Next.js project with npx create next-app which we will use for demonstration. For breadcrumbs to add value, we need to have multiple pages, ideally, with some navigational depth. Without going into into too much detail, we will simply add a few pages representing categories of pets. The possible navigation paths look like this:

Home -> Category -> Variant -> Example pet

Breadcrumbs

We can now proceed to add breadcrumbs to our project starting with the UI part of the breadcrumbs. We will create two components, BreadcrumbsContainer and BreadcrumbsItem. The BreadcrumbsContainer wraps each BreadcrumbsItem which represents a single part of the current path while the BreadcrumbsContainer is responsible for rendering the separator between each BreadcrumbsItem.

const BreadcrumbsItem = ({
  children,
  href,
  ...props
}: BreadcrumbItemProps) => {
  return (
    <li {...props}>
      <Link href={href} passHref>
        {children}
      </Link>
    </li>
  );
};

const BreadcrumbsContainer = ({
  children,
  separator = '/',
}: BreadcrumbsContainerProps) => (
  <nav className="min-h-6 pb-6">
    <ol className="flex items-center space-x-4">
      {Children.map(children, (child, index) => (
        <>
          {child}
          {index < Children.count(children) - 1
            ? <span>{separator}</span>
            : null}
        </>
      ))}
    </ol>
  </nav>
);

With these components we can already create a simple dynamic breadcrumb component which covers many use cases:

import { Children } from 'react';
import { usePathname } from 'next/navigation';

const BreadCrumbs = ({
  children,
}: BreadcrumbsProps) => {
  const paths = usePathname();
  const pathNames = paths.split('/').filter((path) => path);
  const pathItems = pathNames
    .map((path, i) => ({
      // Optionally you can capitalize the first letter here
      name: path,
      path: pathNames.slice(0, i + 1).join('/'),
    }));

  return (
    <BreadcrumbsContainer>
      {pathItems.map((item) => (
        <BreadcrumbsItem key={item.path} href={`/${item.path}`}>
          {item.name}
        </BreadcrumbsItem>
      ))}
    </BreadcrumbsContainer>
  );
};

This component will render a list of breadcrumbs based on the current path. It is great for sites where each path segment has a meaningful name. However, in many cases, the path segments are just IDs or slugs without accessible meaning for the end user. It would be desirable to set the breadcrumbs independent from the current path. Here we will focus only on setting the last item of the breadcrumbs, though the concept can be extended to set all parts of the breadcrumbs.

Breadcrumbs with context

Extending on the previous example, we can add context to set the breadcrumbs component. This will enable us to set the last breadcrumbs item to a value of our choice.

const BreadCrumbsContext = createContext<Context>({
  trailingPath: '',
  setTrailingPath: () => {},
});

const BreadCrumbs = ({
  children,
}: BreadcrumbsProps) => {
  const paths = usePathname();
  const [trailingPath, setTrailingPath] = useState('');
  const context = useMemo(() => ({
    trailingPath,
    setTrailingPath,
  }), [trailingPath]);

  const pathNames = paths.split('/').filter((path) => path);
  const pathItems = pathNames
    .map((path, i) => ({
      name: path,
      path: pathNames.slice(0, i + 1).join('/'),
    }));

  if (trailingPath && pathItems.length > 0 && trailingPath !== pathItems[pathItems.length - 1].name) {
    pathItems[pathItems.length - 1].name = trailingPath;
  }

  return (
    <>
      <BreadcrumbsContainer>
        {pathItems.map((item) => (
          <BreadcrumbsItem key={item.path} href={`/${item.path}`}>
            {item.name === 'loading'
              ? <LoadingSpinner className="w-4 h-4" />
              : item.name}
          </BreadcrumbsItem>
        ))}
      </BreadcrumbsContainer>
      <BreadCrumbsContext.Provider value={context}>
        {children}
      </BreadCrumbsContext.Provider>
    </>
  );
};

The only changes made are the addition of the trailingPath state and the BreadCrumbsContext.Provider which will wrap the page content. If a trailing path is set, it will replace the last item in the breadcrumbs giving us the ability to set the last breadcrumb to a arbitrary value. To actually set the last breadcrumb we introduce the helper useBreadCrumbs which uses the breadcrumb context and sets the trailingPath for us.

export const useBreadCrumbs = (trailingPath?: string) => {
  const context = useContext(BreadCrumbsContext);

  useEffect(() => {
    context.setTrailingPath(trailingPath ? trailingPath : 'loading');
    return () => context.setTrailingPath('');
  }, [trailingPath, context]);
}

Using the Breadcrumbs component

To add breadcrumbs to our site we wrap the child elements in the layout.tsx file

// ...
<BreadCrumbs>
  {children}
</BreadCrumbs>
// ...

We can now set the last breadcrumb using the useBreadCrumbs hook from any page.

const Page = () => {
  useBreadCrumbs('Example pet');

  return (
    <div>
      <h1>Example pet</h1>
    </div>
  );
};

This also works with asynchronous data fetching. For example, we can fetch the pet name from an API and set the breadcrumb when the data is available. It is straightforward to add a loading state while the asynchronous data is being fetched. A full example with some twerks can be found here and checkout this demo of the breadcrumbs.

Localized tRPC errors

gcascio — Sat, 16 Mar 2024 17:47:32 +0000

tl;dr - A method for creating localized error messages with tRPC.

Using a custom error with localization keys

Associating errors with form fields

Full example

There are many cases where you want to present a server error to the user, i.e., when a user tries to sign up with an email that is already in use. In these cases, it's important to present the error message in the user's language. This is a guide on how to do that with tRPC.

We start with a project that was bootstrapped with create-t3-app. For internationalization we use next-intl and set it up as described in the getting started guide. With this initial project setup we can jump into implementing localized error messages.

Getting started

When localizing messages of any kind we need to decide where we want the localization to happen, i.e., the mapping from localization keys to the actual messages. An approach often used is to apply the localization at the last moment, namely, just before the user is presented with it on the client. This way we push the translation to the edge of the application and we can work with localization keys everywhere else.

Essentially, this means we want to send localization keys as part of a tRPC error and then map them to the translations on the client. To achieve this we extend the TRPCError class and add a i18nKey property to it:

import { TRPCError } from '@trpc/server';
import type { useTranslations } from 'next-intl';

type I18nNamespaceKeys = Exclude<Parameters<typeof useTranslations>[0], undefined>;
export type I18nKeys<T extends I18nNamespaceKeys = I18nNamespaceKeys>
  = Parameters<ReturnType<typeof useTranslations<T>>>[0];

export class I18nTRPCError extends TRPCError {
  public readonly i18nKey: I18nKeys;

  constructor(opts: {
    i18nKey: I18nKeys;
  } & ConstructorParameters<typeof TRPCError>[0]) {
    const { i18nKey, ...rest } = opts;
    super(rest);

    this.i18nKey = i18nKey;
  }
}

Additionally, we take advantage of next-intl's types to type the i18nKey property. We can then use this new class to throw localized errors:

throw new I18nTRPCError({
  code: 'BAD_REQUEST',
  message: 'Post with this name already exists',
  i18nKey: 'postAlreadyExistsError',
});

and access the i18nKey property in the client:

const t = useTranslations('posts');

const createPost = api.post.create.useMutation({
  onError: (error) => {
    const message = t(error.data?.i18nKey);
    // Instead of logging it we would present it to the user for example with a toast
    console.log(message);
  },
});

Associating errors with form fields

We can go a step further though. When validating form fields on the server we would like to associate the error with the form field which caused it, so we can present the user with more context on what caused the error. At this point you might have already realized that we can achieve this by adding another field to our custom error, namely, formField which will reference the name of the affected form field:

export class I18nTRPCError extends TRPCError {
  public readonly i18nKey: I18nKeys;

  public readonly formField?: string;

  constructor(opts: {
    i18nKey: I18nKeys;
    formField?: string
  } & ConstructorParameters<typeof TRPCError>[0]) {
    const { i18nKey, formField, ...rest } = opts;
    super(rest);

    this.i18nKey = i18nKey;
    this.formField = formField;
  }
}

we set this field as optional since not every error will be associated with a form field. On the client side we can then use the formField to decide how to present the error. For example, we can use it to set the error message on the exact form field that caused the error:

const t = useTranslations('posts');

const createPost = api.post.create.useMutation({
  onError: (error) => {
    const message = t(error.data?.i18nKey);

    if (!error.data?.formField) {
      // Instead of logging it we would present it to the user for example with a toast
      console.log(message);
      return;
    }

    setError(error.data.formField, { message });
  },
});

You can find a full example of a simple use case which demonstrates how all parts work together here.

Translating zod errors with next-intl

gcascio — Tue, 05 Mar 2024 16:00:40 +0000

tl;dr - An approach to translate zod errors with next-intl
using a zod error map.

Adapt the zod error map and translations provided by zod-i18n

Usage example using a custom hook

When starting a new project with Next.js these days, next-intl and zod are my go to libraries for internationalization and schema validation, respectively. Of course, when using zod for client-facing validations I would like to translate potential error messages. The package zod-i18n can be used to achieve this for i18next, a popular alternative internationalization library. This means that by using this library as starting point one can quickly achieve zod translation with next-intl.

The core piece of zod-i18n is the higher-order function makeZodI18nMap (original here) which returns a zod error map. However, before using this function with next-intl we need make some adaptions.

Getting started

On the code side, what differs between the two packages is mainly the translation functions. Without going into detail, the changes boil down to removing the properties from the translation function which next-intl does not support. Additionally, we need replace the namespace logic used by i18next.

Adapting the error map

When zod encounters a problem when validating a schema, the error map receives an issue to process. This issue carries a path attribute which points to the field which caused the issue. zod-i18n leverages namespaces to translate these paths. With next-intl we need to take a different approach. We simply pass a second translation function tForm to makeZodI18nMap which translates the path and passes it to the original translation function:

export const makeZodI18nMap: MakeZodI18nMap = (option) => (issue, ctx) => {
  const { t, tForm } = {
    ...option,
  };

  // ...

  const path = issue.path.length > 0 && !!tForm
    ? { path: tForm(issue.path.join('.') as any) }
    : {};

  switch (issue.code) {
    case ZodIssueCode.invalid_type:
      if (issue.received === ZodParsedType.undefined) {
        message = t('errors.invalid_type_received_undefined', {
          ...path,
        });
      }
      // ...

Adapting the translations

The next bit to tackle is the translations of the zod errors. Fortunately, both packages use a similar approach for handling translations, namely, json files. The relevant difference is that next-intl uses the ICU message syntax while i18next does not. When adapting the translation, we will make use of the path property we pass to the translation function. For example, the two messages used by i18next

"Number must be exactly {{minimum}}"
“{{path}} must be exactly {{minimum}}"

becomes

"{path, select, missingTranslation {Number} other {{path}}}  must be exactly {minimum}",

Here we use the ICU select syntax to either pick the translation for the path or the literal word “Number” when the path does not match "missingTranslation". There is one downside to this approach, though. To make this selection possible we need to explicitly translate missing translations of paths to "missingTranslation" otherwise the translation key will be shown instead.

Wrapping it up

Only one part is missing now, passing the error map to zod when we want to use it. For this we can write a simple hook:

export const useI18nZodErrors = () => {
  const t = useTranslations('zod');
  const tForm = useTranslations('form');
  z.setErrorMap(makeZodI18nMap({ t, tForm }));
};

Using the translations

With this setup we can finally translate or zod error messages, like in this example:

const schema = z.object({
  username: z.string().min(3),
  age: z.number().min(18),
});

type Schema = z.infer<typeof schema>;

export const ExampleForm = () => {
  useI18nZodErrors();
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<Schema>({
    resolver: zodResolver(schema),
    defaultValues: {
      username: '',
      age: 0,
    }
  });

  return (
    <form onSubmit={handleSubmit((d) => console.log(d))}>
      <input {...register('username')} />
      {errors.username?.message && <span>{errors.username.message}</span>}
      <input type="number" {...register('age', { valueAsNumber: true })} />
      {errors.age?.message && <span>{errors.age?.message}</span>}
      <input type="submit" />
    </form>
  );
};

Some improvements could be made but the result is satisfactory and I have been using it in several projects. You can find the full code on github.

Prototype ChatGPT Apps in Minutes

gcascio — Fri, 09 Jun 2023 09:08:11 +0000

tl;dr - Promptato is a simple setup to quickly showcase some ChatGPT use-cases for the prompt-lazy folks:

Stack: Next.js, Tailwind, OpenAI API

Higher order function maps input definition to prompt definition

I often see that non-tech people are not aware of what tools like ChatGPT can be used for. To quickly showcase some use-cases to friends and family, I built Promptato to easily map user input to prompts and present the results.

Getting started

Essentially, Promptato consists of a higher order function which returns a React component and an API route. Both parts are part of a Next.js project as the underlying app. To get started clone the repo

# ssh
git clone git@github.com:gcascio/promptato.git
# https
git clone https://github.com/gcascio/promptato.git

On first glance there might be a lot going on in the repo but for now we will only focus on the two files src/app/promptato.ts and src/app/page.ts.

To start the application install the required dependencies

pnpm install

create a env.local file (see env.example) and run

pnpm dev

You can then access the application under http://localhost:3000.

Defining the input-prompt mapping

In the file src/app/promptato.ts you will see a single exported value Promptato which is a React component
returned by createPromptato. The higher order function (a function which returns a function) createPromptato is
where all the magic happens. It expects two arguments: an object defining the required inputs and an array defining the
prompts. The clue here is that all values defined in the input definition are available in the in the prompt definition
in a type safe fashion:

As an example, let us create a tool to suggest pizza toppings based on a particular food style. For this we want a select field with food styles to pick from and an input field for the desired number of toppings. Each input is defined using a
schema with the type of component and the user facing label.
Depending on the input type other fields are required, like the options for a select input.

// Food style select component
{
  component: 'select',
  label: 'Choose your food style.',
  options: [
    // ...
  ]
}

// Topping quantity input component
{
  component: 'input',
  label: 'How many toppings would you like?',
  type: 'number'
}

Defining the prompt is an art in itself and we will just use a straightforward approach here.

// role: system
`You are an innovative pizza backer.
You will suggest toppings for a pizza in a given food style and name the pizza.
You must format your response using markdown.`

// role: user
`Food style: ${myFoodStyle}
Limit the number of toppings to ${myLimit}`

That is all it takes to receive our final promptato definition:

export const Promptato = createPromptato({
  foodStyle: {
    component: 'select',
    label: 'Choose your food style.',
    options: [
      'Asian',
      'Greek',
      'Indian',
      'Italian',
      'Tex-Mex',
    ]
  },
  numberOfToppings: {
    component: 'input',
    label: 'How many toppings would you like?',
    type: 'number'
  }
}, [
  {
    role: 'system',
    content:
`You are an innovative pizza backer.
You will suggest toppings for a pizza in a given food style and name the pizza.
You must format your response using markdown.`
  },
  {
    role: 'user',
    content: (input) =>
`Food style: ${input.foodStyle}
Limit the number of toppings to ${input.numberOfToppings}`
  }
])

Using the input-prompt mapping

Now that we have defined our input-prompt mapping, we can continue with src/app/page.ts. All we need to do is import the previously created Promptato component and use it in our page. To create a more appealing app we can sprinkle in some layout and add some headlines

import { Promptato } from './promptato';

const Page = () => (
  <main className="flex flex-col items-center py-24 px-4" data-theme="default">
    <div className="relative flex place-items-center flex-col my-24 max-w-3xl">
      <h1 className="text-4xl sm:text-5xl text-center font-bold pb-4">
        Delicious pizza ideas 🍕
      </h1>
      <h2 className="text-lg sm:text-xl text-center text-slate-700">
        Find mouth watering toppings for your next pizza without being a gourmet cook.
      </h2>
    </div> 

    <section className="w-full max-w-xl">
      <Promptato />
    </section>
  </main>
);

export default Page;

We are all set and can take our finished app for a test ride:

That is all it takes, we have created a ChatGPT-powered app we can easily share with the prompt lazy folks out there.

Type your storage

gcascio — Sat, 06 Mar 2021 10:25:27 +0000

Working with the Storage API - mainly its implementations localStorage and sessionStorage - has become an everyday task for developers since its introduction around 2010. It provides applications with persistent data storage without the need of relying on cookies and it is an important part of modern web apps. Just as the Storage API replaced cookies in many use cases, we are in the middle of yet another trend that seems unstoppable, that is, the shift from using JavaScript to TypeScript for web development. As the State of JS shows, about 78% of JS programmers already use TypeScript, and a good amount of the rest is interested in trying.

Why you should type your store

JavaScript was not made for creating large, complex apps the modern web requires. Therefore, TypeScript aims to address the subsequent problems that arise when developing large systems. One key feature to achieve this is the introduction of static types. Static types are great because it can help to catch errors before running code, thus making code easier to refactor, APIs easier to read and so forth. Unfortunately, when coming from a dynamically typed language like JS it is often very tempting to merely -and brutally- cast types until they fit. To avoid undermining the type system though, lines like the following should be avoided in most cases

const data = apiResponse as undefined as SomeDataType;

Type casts like this one often arise out of inexperience, convenience or are -even- simply unavoidable. However, there is one perfectly avoidable case I keep stumbling across - interactions with the localstorage. The straightforward way of storing and retrieving anything else than a string is

// setting an item
window.localStorage.setItem('my-key', JSON.stringify(data));

//retrieving
const soredData = JSON.parse(window.localStorage.getItem('my-key')) as SomeDataType;

As long as only a couple of things are stored this is not a problem. Nethertheless, the downsides of this approach, namely that there is no type check when adding an item to the store, that it is tedious to type, and the lack of knowledge of how the localStorage looks like, grow as the complexity of the storage grows. Despite this, fear not because I bring good news: we can do better!

How to type your store

By defining our storage structure with a schema similar to the the following

interface Schema {
  counter: number;
  message: string;
  user: {
    id: string;
    name: string;
    email: string;
    isAdmin: boolean;
  };
  posts: string[];
}

We can achieve a more type safe way of interacting with the localStore. Instead of accessing the storage through the bare Storage API, we can now construct a wrapper which takes the schema as the underlying storage structure. The implementation details can be found in my previous post. It boils down to initializing a store once and enjoy a type safe storage access

const typedStorage = new TypedLocalStore<Schema>();

// only allows correct user type
typedStorage.setItem(‘user’, user);

// storedUser is typed
Const storedUser = typedStorage.getItem(‘user’);

The core advantages of this approach are

A single source of truth of the storage structure
Type safe interaction with the storage
Less code duplication

...which fits nicely into the typescript ecosystem. We have had good experience with this approach in context of the virtual presence tool lyno we have been developing. For more insights and to save you some work we published a npm and deno package which incorporates this concept.