DEV Community: Yusuf Aran

Jest: Writing Composable Tests

Yusuf Aran — Mon, 29 Sep 2025 12:02:27 +0000

When writing tests, you often need to spin up the same resources—databases, tables, services—across multiple test cases. At first, jest’s lifecycle hooks (beforeEach, afterEach, beforeAll, afterAll) feel like the right tool for the job. But as soon as your setup and teardown logic gets more complex, these hooks start to show their limits.

The problem? Setup and teardown live in different places, even though they logically belong together. That makes tests harder to read, harder to maintain, and surprisingly easy to get wrong.

This post walks through a example to show the pitfalls of the traditional approach, and then introduces a cleaner pattern using fixtures. Fixtures let you co-locate setup and teardown, build reusable building blocks, and keep your test files concise and self-explanatory.

Issues by Example

Let's analyse common issues with a sophisticated example, which relies on a docker container running with a AWS DynamoDB database. It doesn't matter which technology is used, but I believe it's easier to understand with a close to real world example:

import { DynamoDBClient, CreateTableCommand, DeleteTableCommand, PutItemCommand } from "@aws-sdk/client-dynamodb"
import { LocalstackContainer, StartedLocalStackContainer } from "@testcontainers/localstack"


describe("My Integration Tests", () => {
  let localStackContainer: StartedLocalStackContainer;
  let dynamoDbClient: DynamoDBClient;

  beforeAll(async () => {
    localStackContainer = await (new LocalStackContainer().start())
    dynamoDBClient = new DynamoDBClient({
      endpoint: localStackContainer.getConnectionUri(),
    })
  })

  beforeEach(async () => {
    dynamoDbClient.send(new CreateTableCommand(/* First Table */))
    dynamoDbClient.send(new CreateTableCommand(/* Second Table */))
  })

  afterEach(async () => {
    dynamoDbClient.send(new DeleteTableCommand(/* First Table */))
    dynamoDbClient.send(new DeleteTableCommand(/* Second Table */))
  })

  afterAll(async () => {
    dynamoDBClient.destroy()
    localStackContainer.stop()
  })

  it("gets items from both tables", () => {
   dynamoDbClient.send(new PutItemCommand(/* First Table Item */))
   dynamoDbClient.send(new PutItemCommand(/* Second Table Item */))

   const myService = new Service(dynamoDbClient);
   const items = myService.getItemsFromBothTables();

   expect(items).toEqual(/* .. */)
  })
})

There are few issues when you want to reuse some logic here, which are mainly resulting because of following reason: disconnected setup and teardown.

While beforeEach and afterEach give you the option to define common setup and teardown for every test, the code in these hooks is not co-located. For example these two statements belong together, but are located in different places:

// setup (beforeEach)
dynamoDbClient.send(new CreateTableCommand(/* First Table */))

// teardown (afterEach)
dynamoDbClient.send(new DeleteTableCommand(/* First Table */))

This causes several problems:

Hidden dependency: setup and teardown are logically tied together, but the code is separated, making the relationship hard to see.
Context switching: readers need to jump between different hooks to fully understand the lifecycle of a resource.
Error-prone: it’s easy to accidentally mismatch setup/teardown logic (e.g., creating two tables but only deleting one).
Reduced readability: tests become harder to scan because the lifecycle of resources is fragmented.

The Solution

In the following sections we will find out, how we can solve all of the mentioned issues and more.

Fixtures

Most of these issues can be resolved by using Fixtures. While other test runners like vitest or playwright already provide implementations for fixtures, with jest you have to build a fixtures system yourself.

The main idea of fixtures is to have the setup and teardown logic for that same resource co-located. Fixtures usually have a use function that initializes the fixture, so you can decide in which tests you want to use the fixture.

Let's see how our test could look like with fixtures:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { DynamoDBClientFixture, FirstTableFixture, SecondTableFixture } from "../test/fixtures"


describe("My Integration Tests", () => {
  const dynamoDBClient = DynamoDBClientFixture.use().getClient()
  const firstTable = FirstTableFixture.use(dynamoDBClient)
  const secondTable = SecondTableFixture.use(dynamoDBClient)

  it("gets items from both tables", () => {
   firstTable.putItem(/* .. */)
   secondTable.putItem(/* .. */)

   const myService = new Service(dynamoDbClient);
   const items = myService.getItemsFromBothTables();

   expect(items).toEqual(/* .. */)
  })
})

Now the test file is much more readable and concise. We can exactly see what the test needs to run by looking at the fixtures it uses. All the setup and tear down logic is now encapsulated in fixtures, which makes them easy to reuse.

But how is a fixture implemented? Let's zoom into the FirstTableFixture implementation as an example:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"
import { FirstEntity } from "../../models"

export class FirstTableFixture {
  private constructor(
    private dynamoDbClient: DynamoDBClient
  ) {}

  public static use(dynamoDbClient: DynamoDBClient) {
    const fixture = new FirstTableFixture(dynamoDbClient)

    // put setup and teardown logic directly here
    beforeEach(async () => {
      await fixture.dynamoDbClient.send(new CreateTableCommand({/* .. */}))
    })

    afterEach(async () => {
      await fixture.dynamoDbClient.send(new DeleteTableCommand({ /* .. */ }))
    })

    return fixture
  }

  public putItem(entity: FirstEntity) {
    return this.dynamoDbClient.send(
      new PutItemCommand({/* .. */}),
    )
  }
}

Following are the characteristics of a fixture here:

A fixture is a class that at the minimum has a use function and is mostly responsible for a single resource (here the FirstTable).
The use function returns an instance of the fixture class or undefined. It can optionally receive some arguments.
The use function calls global jest hooks, like beforeEach and afterEach. Yes, you can call these hooks anywhere! jest will call these hooks in the same order as they were called.
A fixture optionally provides additional functions which can be getters or allow actions on the resource. For example the putItem function allows type-safe inserts to the table. This is also the main reason why I chose to use a class instead of a factory function for fixtures.

You can now implement a fixture for each resource and create resuable building blocks for your tests.

Global Setup & Teardown (advanced)

As you might have noticed, I omitted the LocalStack part in the fixture examples completely. Starting a docker container can actually take quite some time so it makes sense to reuse the same container for multiple test files.

In your jest.config you can define globalSetup and globalTeardown files. Unfortunately, these require a function to be exported from two different files, which is why I usually create a helper file first:

// local-stack.ts
import { LocalstackContainer, StartedLocalStackContainer } from "@testcontainers/localstack"

// You only need this if you want to pass variables
// from your global setup to your test files and fixtures
declare global {
  var localStackContainer: StartedLocalStackContainer
}

export const startLocalStack = async () => {
  const localStackContainer = new LocalstackContainer("localstack/localstack:3.1")
  global.localStackContainer = await localStackContainer.start()
  return global.localStackContainer
}

export const stopLocalStack = async () => {
  if (global.localStackContainer) {
    return global.localStackContainer.stop()
  }
  return Promise.resolve()
}

// Can be used in test files and fixtures
export const getLocalStackContainer = () => {
  if (globalThis.localStackContainer) {
    return globalThis.localStackContainer
  }
  throw new Error("LocalStack container is not started")
}

Now you can create minimal global setup/teardown files:

// localstack-setup.ts
import { startLocalStack } from "./local-stack"

export default startLocalStack

// localstack-teardown.ts
import { stopLocalStack } from "./local-stack"

export default stopLocalStack

This way the main logic still resides in a single file.

There might also be cases where you want to have different global setup/teardown logic for different parts of your tests. Maybe one set of test files requires not just a LocalStack container, but also a PostgreSQL container. Here you can use the projects option with different global setup/teardown files:

Note:
maxWorkers is set to 1 to prevent parallel tests from conflicting over the same Docker container. Running projects in parallel would be preferable, but it’s not yet supported (see open GitHub issue).

// postgres-and-localstack-setup.ts
import { startPostgres } from "./postgres"
import { startLocalStack } from "./local-stack"

const postgresAndLocalstackSetup = async () => {
  await Promise.all([startPostgres(), startLocalStack()])
}

export default postgresAndLocalstackSetup

// postgres-and-localstack-teardown.ts
import { stopPostgres } from "./postgres"
import { stopLocalStack } from "./local-stack"

const postgresAndLocalstackSetup = async () => {
  await Promise.all([stopPostgres(), stopLocalStack()])
}

export default postgresAndLocalstackSetup

// jest.config.ts
import { JestConfigWithTsJest } from "ts-jest"

const jestConfig: JestConfigWithTsJest = {
  // ..
  maxWorkers: 1,
  projects: [
    {
      // ..
      displayName: "dynamodb-sync-test",
      testMatch: ["<rootDir>/src/dynamodb-sync/**/*.test.ts"],
      globalSetup: "<rootDir>/test/global-environments/localstack-setup.ts",
      globalTeardown: "<rootDir>/test/global-environments/localstack-teardown.ts",
    },
    {
      // ..
      displayName: "postgres-sync-test",
      testMatch: ["<rootDir>/src/postgres-sync/**/*.test.ts"],
      globalSetup: "<rootDir>/test/global-environments/postgres-and-localstack-setup.ts",
      globalTeardown: "<rootDir>/test/global-environments/postgres-and-localstack-teardown.ts",

    },
  ],
}

export default jestConfig

Now test files can share the same resource globally, which can save a lot if time when executing tests.

Further Considerations & Ideas

Here are a few additional points that might help you get along with the fixture architecture:

Use beforeAll/afterAll depending on your needs in the use functions as well
You can still use hooks in your test file, to e.g. setup data specific to a describe block:

describe("My Integration Tests", () => {
  // .. 
  const firstTable = FirstTableFixture.use(dynamoDBClient)

  beforeEach(() => {
    firstTable.putItem(/* .. */)
  })

  it("first test", () => {})
  it("second test", () => {})
})

If you are starting out a new project, you might just want to use vitest as it already comes with a build-in fixtures system.

Conclusion

Writing clean and maintainable tests isn't just about assertions, it’s also about managing setup and teardown in a way that's readable, reusable, and composable. While jest's beforeEach/afterEach hooks cover the basics, they quickly become messy when resources have disconnected lifecycles. By introducing fixtures, you can co-locate setup and teardown logic, eliminate hidden dependencies, and build reusable building blocks that make your tests easier to reason about.

Combined with global setup and teardown for expensive resources like Docker containers, this approach gives you a structured testing architecture that scales with your codebase. Whether you continue with jest or switch to a runner like vitest that provides fixtures out of the box, thinking in terms of fixtures will help you write tests faster and make them clearer and more maintainable.

How to use Playwright with GitHub Actions and GitHub Pages

Yusuf Aran — Wed, 30 Nov 2022 18:19:34 +0000

Introduction

Playwright is a modern cross-browser testing framework developed by microsoft itself.
GitHub Actions is the out-of-the-box solution for anything related to CI/CD pipelines on GitHub.
Last but not least GitHub Pages is a GitHub feature which allows to deploy static websites.

And all of this comes completely free for public repositories!

In this blog post I will show you how to setup a basic a Playwright project, integrate it into GitHub Actions and finally deploy an HTML report of the test results to GitHub Pages.

ℹ️ INFO
The complete source code can be found in this repo: ysfaran/playwright-gh-actions-gh-pages

This post is not focusing on explaining all concepts of Playwright, but rather how to connect Playwright, GitHub Actions and GitHub Pages in a easy, non-cost way.

Setup Playwright

💡TIP
For an up-to-date installation guide please always refer to https://playwright.dev/docs/intro. At the point of writing this posts Playwright's latest version was 1.25.1.

Fortunately Playwright makes it really easy to setup a new project using the CLI:

yarn create playwright

This will start an interactive session. Make sure to at least enable GitHub Action workflow generation. Following is the configuration I used:

✔ Do you want to use TypeScript or JavaScript? · TypeScript
✔ Where to put your end-to-end tests? · tests
✔ Add a GitHub Actions workflow? (y/N) · true

Generate HTML Report

One of the most important generated files is playwright.config.ts, so let's have a look at it:

ℹ️ INFO
I simplified some of the generated files. For a full list of these changes see aab0b9c2.

const config: PlaywrightTestConfig = {
  testDir: "./tests",
  // Run all tests within a file in parallel to speed up test execution
  fullyParallel: true,
  // Helpful for uncontrollable flaky tests, which are tests, occasionally failing for various reasons
  retries: 3,
  // Generates a HTML report to ./playwright-report/
  reporter: "html",
  use: {
    // Tests will be run against this page
    baseURL: "https://playwright.dev/",
    // Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer
    trace: "on-first-retry",
  },
  // Cross-browser testing setup
  projects: [
    {
      name: "chromium",
      use: {
        ...devices["Desktop Chrome"],
      },
    },
    {
      name: "firefox",
      use: {
        ...devices["Desktop Firefox"],
      },
    },

    {
      name: "webkit",
      use: {
        ...devices["Desktop Safari"],
      },
    },
  ],
};

Since the html reporter is already enabled by default, there are no other adaption necessary.
To get a nice HTML report covering all test result cases (sucess, fail and flaky) following tests have been implemented:

import { test, expect } from "@playwright/test";

test.beforeEach(({ page }) => page.goto("https://playwright.dev/"));

test("should succeed", async ({ page }) => {
  await expect(page).toHaveTitle(/Playwright/);
});

test("should fail", async ({ page }) => {
  await expect(page).not.toHaveTitle(/Playwright/);
});

test("should be flaky", async ({ page }) => {
  if (Math.random() > 0.5) {
    await expect(page).toHaveTitle(/Playwright/);
  } else {
    await expect(page).not.toHaveTitle(/Playwright/);
  }
});

To run the tests execute:

npx playwright test

After running all tests Playwright prints a summary of test restuls and publishes the HTML report to a server at a localhost address. Playwright also emits all sources for the HTML report to playwright-report/.

Integrate GitHub Actions

Luckily Playwright already generated a basic .github/workflows/playwright.yml during Setup Playwright to integrate Playwright tests into a GitHub Actions worklow:

name: Playwright Tests
on:
  push:
    branches: [main, master]
jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: "14.x"
      - name: Install dependencies
        run: yarn
      - name: Install Playwright Browsers
        run: npx playwright install --with-deps
      - name: Run Playwright tests
        run: yarn playwright test
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Essentially the workflow is triggered on every push and executes the all tests, just like you would do it locally.
It's important to note that it also uploads the Playwright HTML report as workflow artifact.
This artifact will be available to download in the Actions tab of your GitHub repository in each workflow run.

Please refer to the official Playwright docs on how to download and view HTML report files of a specific workflow run.

Publish HTML Report to GitHub Pages

Being able to download, view and debug HTML reports generate by a CI/CD pipeline locally is already convenient, but there is an easier and faster way to check test results: automatically publish the HTML reports to GitHub Pages and view them directly in the browser.

Firstly a new orphan branch, which means the branch has no parent commit, for the GitHub Pages' static content needs to be created:

# Create a new branch without any commit on it
git checkout --orphan gh-pages

# Source files get autoamtically staged so remove them from git
git rm -rf .

# Optional: Check if there are really no files in the git staging area anymore
git status

# Create an initial, empty commit
git commit --allow-empty -m "setup empty branch for GitHub Pages"

# Push the branch to make it available online
git push --set-upstream origin gh-pages

Secondly the GitHub Pages feature needs to be enabled for your repo. Usually GitHub is enabling GitHub Pages automatically when you name a branch gh-pages.
If it doesn't, make sure to enable GitHub Pages manually in your repository settings:

Any change that is pushed to gh-pages will now automatically update the GitHub Pages website, which is publicly available at https://<user>.github.io/<repo>/.
Because there is no real commit on the gh-pages branch yet a 404 error page will be shown.

So the next logical step is to add a new job to the GitHub Actions workflow in order to push the HTML reports to gh-pages branch:

publish_report:
  name: Publish HTML Report
  # using always() is not ideal here, because it would also run if the workflow was cancelled
  if: "success() || needs.test.result == 'failure'"
  needs: [test]
  runs-on: ubuntu-latest
  continue-on-error: true
  env:
    # Unique URL path for each workflow run attempt
    HTML_REPORT_URL_PATH: reports/${{ github.ref_name }}/${{ github.run_id }}/${{ github.run_attempt }}
  steps:
    - name: Checkout GitHub Pages Branch
      uses: actions/checkout@v2
      with:
        ref: gh-pages
    - name: Set Git User
      # see: https://github.com/actions/checkout/issues/13#issuecomment-724415212
      run: |
        git config --global user.name "github-actions[bot]"
        git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
    - name: Download zipped HTML report
      uses: actions/download-artifact@v2
      with:
        name: playwright-report
        path: ${{ env.HTML_REPORT_URL_PATH }}
    - name: Push HTML Report
      timeout-minutes: 3
      # commit report, then try push-rebase-loop until it's able to merge the HTML report to the gh-pages branch
      # this is necessary when this job is running at least twice at the same time (e.g. through two pushes at the same time)
      run: |
        git add .
        git commit -m "workflow: add HTML report for run-id ${{ github.run_id }} (attempt:  ${{ github.run_attempt }})"

        while true; do
          git pull --rebase
          if [ $? -ne 0 ]; then
            echo "Failed to rebase. Please review manually."
            exit 1
          fi

          git push
          if [ $? -eq 0 ]; then
            echo "Successfully pushed HTML report to repo."
            exit 0
          fi
        done
    - name: Output Report URL as Worfklow Annotation
      run: |
        FULL_HTML_REPORT_URL=https://ysfaran.github.io/playwright-gh-actions-gh-pages/$HTML_REPORT_URL_PATH

        echo "::notice title=📋 Published Playwright Test Report::$FULL_HTML_REPORT_URL"

Basically this job commits the HTML report files to the gh-pages branch, which will then automatically redploy the website.

It does so by specifying a new unique path for each test result:

HTML_REPORT_URL_PATH: reports/${{ github.ref_name }}/${{ github.run_id }}/${{ github.run_attempt }}

The job then tries to push these changes and rebases if necessary until a push was succssful.
Rebasing is safe here, because - as already mentioned - each workflow run gets its own uniquie path, so there can't be any file conflicts ever.

Last but not least the publicly available URL is printed as GitHub Worfklow Annotation:

💡 TIP
It might take some while for GitHub Pages to update its content after a new push, so the printed URL will point to a 404 page initially.
In the Actions tab of your repo you can check pages-build-deployment workflow runs, which is automatically triggered for GitHub Pages, to see if the GitHub Pages deployment was successful.

Add Multi-Branch Support

Only in rare cases you work on a single branch. Also the pipeline is currently not integrated in any pull request process, meaning that there are no restriction to push or even force push to your main/master.
Its time to change that!

First of all we need to enable branch protections rules for the default branch:

Go to the settings of your repo
Select Branches under Code and automation in the menu
Hit the Add branch protection rule button
Add your default branchs name for Branch name pattern
Configure your branch protecting rules as desired, most importantly being:

Note that I only put Test under Status checks that are required. because you should still be allowed to merge to main branch if some HTML report couldn't be published.
A green Test job for a branch represents a valid state anyway in this case.

Secondly the workflow needs to be adapted:

on:
  push:
-    branches: [ main, master ]
-  pull_request:
-    branches: [ main, master ]
+    branches-ignore: [ main, gh-pages ]

So the workflow is triggered after each push on every branch except main and gh-pages.
I purposely removed pull_request here, because it's really hard (at this point in time) to make push and pull_requests work together with GitHub Actions.
Feel free to check my answer on StackOverflow answer regarding this topic.

⚠️ CAUTION
If you want to work with pull_request every occurence of ${{ github.ref_name }} should be replaces with ${{ github.head_ref || github.ref_name }}.
Check the related StackOverflow answer for details: https://stackoverflow.com/a/71158878/6489012.

I also highly recommend to enable concurrency groups in your workflow file to make sure only one workflow is running at the same time for each branch:

concurrency:
  group: ${{ github.ref_name }}
  # optional
  cancel-in-progress: true

Delete Reports from GitHub Pages

After a branch was successfully merged it makes sense to delete all corresponding HTML reports from GitHub Pages. This requires the implementation of a new workflow file:

name: Delete

on:
  delete:
    branches-ignore: [main, gh-pages]

# ensures that currently running Playwright workflow of deleted branch gets cancelled
concurrency:
  group: ${{ github.event.ref }}
  cancel-in-progress: true

jobs:
  delete_reports:
    name: Delete Reports
    runs-on: ubuntu-latest
    env:
      # Contains all reports for deleted branch
      BRANCH_REPORTS_DIR: reports/${{ github.event.ref }}
    steps:
      - name: Checkout GitHub Pages Branch
        uses: actions/checkout@v2
        with:
          ref: gh-pages
      - name: Set Git User
        # see: https://github.com/actions/checkout/issues/13#issuecomment-724415212
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
      - name: Check for workflow reports
        run: |
          if [ -z "$(ls -A $BRANCH_REPORTS_DIR)" ]; then
            echo "BRANCH_REPORTS_EXIST="false"" >> $GITHUB_ENV
          else
            echo "BRANCH_REPORTS_EXIST="true"" >> $GITHUB_ENV
          fi
      - name: Delete reports from repo for branch
        if: ${{ env.BRANCH_REPORTS_EXIST == 'true' }}
        timeout-minutes: 3
        run: |
          cd $BRANCH_REPORTS_DIR/..

          rm -rf ${{ github.event.ref }}
          git add .
          git commit -m "workflow: remove all reports for branch ${{ github.event.ref }}"

          while true; do
            git pull --rebase
            if [ $? -ne 0 ]; then
              echo "Failed to rebase. Please review manually."
              exit 1
            fi

            git push
            if [ $? -eq 0 ]; then
              echo "Successfully pushed HTML reports to repo."
              exit 0
            fi
          done

The job of this workflow is pretty similiar to the one publishing the HTML report. This time it's just the other way around: gh-pages branch is checked out and the folder reports/<branch-name> is deleted.
Then the same push-rebase loop is initated to trigger a GitHub Pages deployment.

Important to note here is the following part:

ℹ️ INFO
This time the name of the (deleted) branch is neither retreived by github.head_ref and github.ref_name, but github.event.ref.
In case the workflow was triggered by a delete the value of github.ref_name will be the one of the default branch, here main.

concurrency:
  group: ${{ github.event.ref }}
  cancel-in-progress: true

This statement makes sure that any running workflow within the same concurrency group will be cancelled.
In our case this means if tests for a deleted branch are still running, they will be cancelled.

Conclusion

We created a Playwright project from scratch, integrated tests in GitHub Actions, deployed test results to GitHub Pages and finally established branch protections rules with a simple but important pull request strategy.
All of this, without any costs.

All in all it's all about automation and process optimization. Keeping a team busy with daunting manual tasks can decrease effincy and motivation quite a bit.
This can go from manual deployment plans to smaller aspects like hard to debug test results. In the long run saving some minutes of daily, manual work can have a huge impact.

Questions and feedback are always welcome. 🙂

useStateWithPromise: a custom hook to await state updates of useState

Yusuf Aran — Sat, 18 Apr 2020 20:08:55 +0000

Originally posted on my blog.

The Problem

The general problem is that we want to wait for a state update an then do something afterwards. Unfortunatly we can not write sequential code, because every state update is asynchronous.
In "old" react we could simply pass a callback. As an example we will look at a class component, that contains filters for an article list view:

class FilterSidebar extends React.Component {
  constructor(){
    this.state = {
      filters: {},
      articles: []
    }
  }

  fetchArticles = async () => {
    const fetchedArticles = await API.getArticles(this.state.filters);
    this.setState({articles: fetchedArticles})
  }

  reset = () => {
    this.setState({filters: {}}, this.fetchArticles);
  }

  setColorFilter = (color) =>  {
    this.setState(state => ({filters: {...state.filters, color}));
  }

  // more filters & render ...
}

fetchArticles: fetch articles from an API service based on the filters in the state.
reset: clear all filters and then fetch articles, by passing fetchArticles as callback to setState. This will guarantee that the state of filters is cleared before calling fetchArticles
setColorFilter: sets filter for articles to have a specific color (just an example to help your imagination!)

Using functional components this would look a bit different:

const FiltersSidebar = () => {
  const [articles, setArticles] = useState([]);
  const [filters, setFilters] = useState({});

  const fetchArticles = async () => {
    const fetchedArticles = await API.getArticles(filters);
    setArticles(fetchedArticles)
  }

  const reset = () => {
    setFilters({});

    // uuhh, ouhh .. fetchArticles will use old state of "filters"
    fetchArticles();
  }

  const setColorFilter = (color) =>  {
   setFilters(currentFilters => ({...currentFilters, color}));
  }

  // more filters & return ..
}

The problem here is that the setter, which is returned by useState (here setFilters), doesn't allow us to pass a callback function as second argument. But in this case we can use useEffect and useRef to handle the problem:

const FiltersSidebar = () => {
  const [articles, setArticles] = useState([]);
  const [filters, setFilters] = useState({});
  const resettingRef = useRef(false);

  const fetchArticles = async () => {
    const fetchedArticles = await API.getArticles(filters);
    setArticles(fetchedArticles)
  }

  const reset = () => {
    resettingRef.current = true;
    setFilters({});
  }

  useEffect(() => {
    if(resettingRef.current){
      resettingRef.current = false;
      fetchArticles();
    }
  },[filters])

  // ...
}

Okay, that looks a bit ugly but at least it works..
But what happens if the filter logic gets much more complicated and we want to extract logic for filters in custom hooks:

const useStringFilter = (initialValue = "") => {
  const [value, setValue] = useState(initialValue);

  // maybe more complex stuff here

  const reset = () => {
    setValue(initialValue)
  }

  return {
    value,
    setValue,
    reset
  }
}

// and filters for other types like useDateFilter etc..

Then our component could look like this:

const FiltersSidebar = () => {
  const [articles, setArticles] = useState([]);

  const colorFilter = useStringFilter();
  const nameFilter = useStringFilter();
  const releaseDateFilter = useDateFilter();

  const fetchArticles = async () => {
    const filters = {
      color: colorFilter.value,
      name: nameFilter.value,
      releaseDate: releaseDateFilter.value
    }
    const fetchedArticles = await API.getArticles(filters);
    setArticles(fetchedArticles)
  }

  const reset = () => {
    colorFilter.reset(); // will trigger a state update inside of useStringFilter
    nameFilter.reset(); // will trigger a state update inside of useStringFilter
    releaseDateFilter.reset(); // will trigger a state update inside of useDateFilter

    // fetchArticles will use old state of colorFilter, nameFilter and releaseDateFilter
    fetchArticles();
  }

  // ...
}

What to do now?

There is no straightforward way when using useEffect and useRef anymore, because we need to wait for multiple state updates to be completed. And that exactly is the actual problem!

The Solution

With a custom hook - namely useStateWithPromise - this problem can be solved:

const useStateWithPromise = (initialState) => {
  const [state, setState] = useState(initialState);
  const resolverRef = useRef(null);

  useEffect(() => {
    if (resolverRef.current) {
      resolverRef.current(state);
      resolverRef.current = null;
    }
    /**
     * Since a state update could be triggered with the exact same state again,
     * it's not enough to specify state as the only dependency of this useEffect.
     * That's why resolverRef.current is also a dependency, because it will guarantee,
     * that handleSetState was called in previous render
     */
  }, [resolverRef.current, state]);

  const handleSetState = useCallback((stateAction) => {
    setState(stateAction);
    return new Promise(resolve => {
      resolverRef.current = resolve;
    });
  }, [setState])

  return [state, handleSetState];
};

It's not important to fully understand this hook. But what you should understand is that useStateWithPromise returns, just like useState, a getter and setter with a small important difference:

the setter returns a Promise, which we can await!

Now we can replace the useState statements in our custom filter hooks with useStateWithPromise:

const useStringFilter = (initialValue = "") => {
  const [value, setValue] = useStateWithPromise(initialValue);

  const reset = () => {
    // this will return a promise containing the updated state
    return setValue(initialValue);
  }

  return {
    value,
    setValue,
    reset
  }
}

And then we can finally await state updates:

const FiltersSidebar = () => {
  // ...

  const reset =  async () => {
    // wait for all state updates to be completed
    await Promise.all([
      colorFilter.reset(),
      nameFilter.reset(),
      releaseDateFilter.reset()
    ]);

    // fetchArticles will STILL use old state of colorFilter, nameFilter and releaseDateFilter
    fetchArticles();
  }

  // ...
}

Well, that was a WT.. moment for me, but it makes sense if you really think about how functional components work.

Viewing the code from plain JavaScript side (without react) reset is just a function inside of a function(al component). So each time the function is called (in the react terms: the functions is rerendered), reset will be a new function with a new reference. After we await the state updates of the filters with Promise.all, reset will still point to the exact same "old" fetchArticles reference, which is still pointing to "old" state! But in the meantime multiple state updates happend and there is much "newer" version of reset and also fetchArticles, which is pointing to the updated state.

With one additional state property, here resetted, this can be fixed:

const FiltersSidebar = () => {
  // ...
  const [resetted, setResetted] = useState(false)

  useEffect(() => {
    if(resetted){
      fetchArticles();
      setResetted(false);
    }
  },[resetted]);

  const reset =  async () => {
    await Promise.all([
      colorFilter.reset(),
      nameFilter.reset(),
      releaseDateFilter.reset()
    ]);

    setResetted(true);
  }

  // ...
}

Now setResetted(true) will trigger a rerender of the component and it's guaranteed that the fetchArticles call inside of the useEffect statement will use the latest state for the API call.

The Solution ?

When I implemented useStateWithPromise I really thought that's the perfect solution and also questioned why there is no build-in solution for this in react? But after my WT.. moment I really understood why react didn't include such functionality:

It simply doesn't fit to the general design of functional components!

When you use class components, you work a lot with mutable references (e.g. this.state is reference that constantly gets updated by this.setState calls). But that's an anti pattern for functional components, because here you always try to work with immutable data and there is a reason for that:

Mutable references tend to cause unwanted side effects!

If your state has a non-primitive type (e.g. an object or array) it's recommended create new references instead of keeping the old one:

const MyComponent = () => {
  const [immutableData, setImmutableData] = useState({a: "a", b: "b"});
  let [mutableData, setMutableData] = useState({a: "a", b: "b"});


  const setNewData = () => {
    // good: new reference!
    setImmutableData({a: "new a", b: "new b"})

    // bad: same reference!
    mutableData.a = "new a";
    mutableData.b = "new b";
    setMutableData(mutableData)
  }

  useEffect(() => { console.log("immutable data changed") }, [immutableData])

  // will never be called because mutableData will always have same reference
  useEffect(() => { console.log("mutable data changed") }, [mutableData])

  return (
    <>
      <ChildComponent data={immutableData} />
      {/**
        * changing mutableData without the state setter, (e.g. mutableData.a = "new a")
        * could cause unwanted side effects, because ChildComponent wouldn't be rerendered,
        * so e.g. no useEffect statements inside ChildComponent would be triggered
        */}
      <ChildComponent data={mutableData} />
    </>
  )
}

To come back to the example:

each state update (e.g. reset of filter) causes a rerender
each rerender creates a new reference for reset and fetchArticles
each fetchArticles reference will point to a different immutable state
after the await in reset the fetchArticles call will use "old" state, because it's an "old" version of fetchArticles

So the general issue is that we have multiple fetchArticles versions (after each render) which all point to different states, because states in functional components are/should be immutable.

Conclusion

There is a reason why react didn't implement this feature for functional components. If you have the time and the ability to (re-)build the architecture of your app, you should really think about using useStateWithPromise.

I used it once in production, but only because the time was limited and my customer didn't want to spent to much time refactoring the code. For the next project I had a similiar problem but was able to switch the approach and solve this problem differently. E.g. in our example the actual problem was that we had multiple states in multiple hooks but could not reset them easily all at once (we needed to call reset on each filter). If the state of all filters would be in one place, it would be much easier to reset them all together. A different approach would be to store inital values in a ref so it's not even necessary to wait for the state to be updated.

As final conclusion: If you have the necessarity to await state updates in a manner like with useStateWithPromise you either have a non-ideal architechture, your requirments have changed or you have a really special case. 😉

react-fluent-form: How to write forms with validation in few steps

Yusuf Aran — Tue, 31 Mar 2020 10:59:50 +0000

Originally posted on my blog.

Background

Maybe you know how complicated react state handling for forms - including validation - can be and you already researched for a library that fits to your use case. To make things more complicated we often implement custom fields or use third party libraries like react-select.

I was not satisfied (at least not 100%) with any solution on npm so I developed a form library myself:

ysfaran / react-fluent-form

A form library for react, which provides a fluent API.

Why are you not satisfied with existing solutions?

DISCLAIMER:
Of course every library has its up- and downsides (also mine..) and there are for sure great form libraries out there! But I just want to highlight the topics that annoyed me personally.

The libraries I found and also used in some of my projects were not intuitive enough. I'm a simple guy who wants a simple API!
Some libraries came with a lot of boilerplate code.
I used a lot of custom fields and all libraries forced me to something I didn't like (e.g. wrap my custom field in another component) or didn't support customization in the level I would like it.
Many libraries had no easy-to-use validation approach.
Missing features like form arrays.

Why is react-fluent-form satisfying your needs?

It (hopefully) provides a more intuitive fluent API.
It comes with a easy-to-use validation approach using yup schemes. If you don't like yup, you can also write your custom validator!
Customization is made fairly easy, because you can add as many reusable custom fields as required, without touching any component.
It reduces boilerplate code by enabling a simple API.

Stop talking. Let's code!

Talking is good, showing is better! The next section will go step by step through the creation proccess of a form using react-fluent-form.

1. Configuring the form

The heart of react-fluent-form is the form config since it's the part of it that actually provides the fluent API:

NOTE:
All code snippets will be in typescript, because the library is also written in typescript!

import * as yup from "yup";
import { createForm, field } from "react-fluent-form";

interface RegistrationForm {
  username: string;
  password: string;
}

const formConfig = createForm<RegistrationForm>()({
  username: field.text("user0"),
  password: field.password().validateOnSubmitOnly(),
}).withValidation({
  username: yup.string().required().min(4),
  password: yup.string().required().min(8)
})

STOP! Try to understand what's happening. Let me know in the comments if you already understand the code without ever seeing it before! Thanks!!

Okay, so we just specified how our registration form will look like:

It will have two input fields: Username and Password
- Username will have the default value user0
- Password will be an empty string
- It will also trigger validation for Password only when a submit has been initiated. There are more validation triggers available but the default is validateAfterTouchOnChange, which means once the field lost focus it will be validated after each change.
- field.text() and field.password() actually represent the options for the type property of the HTML input element
We added validation for each field using yup schemes. Those schemes perfectly fit into react-fluent-form since yup also provides a fluent API!
- Username is a required string and must have at least length of 4 characters
- Password is required string and must have at least length of 8 characters

2. Initializing the form

Cool, we configured our form but that was just plain typescript, no react involved. react-fluent-form comes with a set of react hooks, but the most important one is useFluentForm:

const RegistrationForm = () => {
  // We just used the config we created before and that's all we need!
  const { values, touched, validity, errors /* and more */ } = useFluentForm(formConfig);

  // ...
}

Among other things useFluentForm returns:

values: it's an object that contains the current values entered to the form. In this example it would look like {username: "user0", password: ""} in the beginning.
touched: it's an object that stores information about the touched state of each field. A field is touched once it had focus and then lost it, so from a technical perspective if the onBlur event of an input field was triggert. An example object could be {username: true, password: undefined} (undefined means it was not touched yet).
validity: it's an object that stores information about the validation state of each field. It could look like {username: false, password: undefined} (undefined means it was not validated yet).
errors: it's an object that contains the current errors of each field in the form. In case of an error the evaluation of yup schemes will result in a string[] type, so the errors object could look like {username: ["username is a required field"], password: undefined } (undefined means the field was not validated yet or that it's valid).

3. Rendering the form

We set up all logic, let's start rendering our form now:

function RegistrationForm() {
  const { values, fields, errors, handleSubmit } = useFluentForm(formConfig);

  const handleSubmitSuccess = () => console.log(values);

  const handleSubmitFailure = () => console.log(errors);

  return (
    <form onSubmit={handleSubmit(handleSubmitSuccess, handleSubmitFailure)}>
      <label>
        Username*:
        <input {...fields.username} />
      </label>
      <label>
        Password*:
        <input {...fields.password} />
      </label>
      <button type="submit">Submit</button>
    </form>
  );
}

And that's it! But wait we have two new properties here:

fields: is an object that contains the props for the to render component. As you might remember react-fluent-form exports a field variable that allowed us to specify the type of the input field (e.g. field.password()). It supports every reasonable HTML input type like checkboxes or radio buttons and also the HTML elements textarea and select. So in our example fields would have following type:

{
  username: {
    type: "text";
    value: string;
    onChange: (e: ChangeEvent<HTMLInputElement>) => void;
    onBlur: () => void;
  },
  password: {
    type: "password";
    value: string;
    onChange: (e: ChangeEvent<HTMLInputElement>) => void;
    onBlur: () => void;
  },
}

handleSubmit: is a function that returns a callback for the form submission. Optionally it allows us to pass a success and failure callback, which are called dependent on the validation result of the whole form. If at least one field is invalid, failure will be called, otherwise success.

4. Displaying feedback messages

This is actually not mandatory but it surly improves UX! For simple error displays you can just add a check on the errors object and display it if there is one:

const RegistrationForm = () => {
 //...

  return (
    <form onSubmit={handleSubmit(handleSubmitSuccess, handleSubmitFailure)}>
      <label>
        Username*:
        <input {...fields.username} />
        {errors.username && <div> {errors.username[0]} </div>}
      </label>
      <label>
        Password*:
        <input {...fields.password} />
        {errors.password && <div> {errors.password[0]} </div>}
      </label>
      <button type="submit">Submit</button>
    </form>
  );
}

If the feedback process is more complex (e.g. you want to show if a field is valid, not just if it's invalid) you can take advantage of information stored in validity and touched.
I'm sure you will find a good solution for your needs!

Customization

So we talked a lot about a very simple form, but until here I would just hate my own library. Why? Because every project is different and every application has different requirements. It's cool and very useful that standard HTML elements are supported, but when did you use a standard HTML select element or an standard HTML datepicker the last time? I mean they are very hard to customize (sometimes it's not even possible) and they don't support features mandatory for professional UX.

Okay, I calmed down. Let's focus on the code again!

Customizing fields

For simple components like react-datepicker react-fluent-form provides field.raw().

What means simple component in this context?

it has value-like and a onChange-like prop
value has the same type as the first parameter of onChange handler
it optionally has a onBlur-like prop to indicate when the field is touched

*-like means it must not have the same name, but the same type. E.g. the value prop in react-datepicker is called selected.

For raw fields it's required to pass an initial value, otherwise it will be undefined:

type DateValue = Date | null;

const formConfig = createForm()({
  dateOfBirth: field.raw<DateValue>(null).withValueProp("selected")
});

The type of fields object would look like this:

type FieldsType = {
  dateOfBirth: {
    selected: Date | null;
    onChange: (newValue: Date | null) => void;
    onBlur: () => void; // will just set the "touched" state to true
  };
};

On default field.raw will be mapped to properties value, onChange and onBlur. Names of these properties can easily be changed using withValueProp (as in the example), withOnChangeProp and withOnBlurProp.
But, oh boy, I would not like to write

field.raw<DateValue>(null).withValueProp("selected")

each time I need a datepicker.

A simple approach is to wrap it in a function:

const datePicker = (initialValue: DateValue = null) => {
  return field.raw<DateValue>(initialValue).withValueProp("selected")
}

const formConfig = createForm()({
  dateOfBirth: datePicker()
});

But to me that looks kind of odd if put next to other fields:

const formConfig = createForm<RegistrationForm>()({
  username: field.text("user0"),
  dateOfBirth: datePicker(),
  password: field.password().validateOnSubmitOnly()
})

Ideally I would like to have field.datePicker() so it fits perfectly to the rest of the library. For this purpose react-fluent-form exports a utility function addField:

import { addField, RawField, field } from "react-fluent-form";

addField("datePicker", (initialValue: DateValue = null) =>
  field.raw(initialValue).withValueProp("selected")
);

and then you can just use field.datePicker() anywhere you want!

But wait, there are few things to note down here:

addField needs to be called in a top level file, which means addField statements need to be executed before e.g. field.datePicker() is used somewhere.
For Typescript users (like me) this gets a bit more complicated. Typescript will not know about field.datePicker() until we tell the compiler about it. Since types always need to be known at compile time, this part can't be handled by the library itself.

import { RawField } from "react-fluent-form";

declare module "react-fluent-form" {
  interface FieldCreator {
    datePicker: (initialValue?: DateValue) => RawField<DateValue, "selected">;
    // add more custom fields here
  }
}

For customization of configurable/complex fields please have a look at official react-fluent-form docs.

Customizing validation

Equally to form state handling, form validation handling is really important topic on modern websites. So it's important to have a flexible and easy to use validation approach.

That's why react-fluent-form makes validation customizable.
Instead of a yup schema you can also provide a function which receives:

the current value of the to validate field
the current values of the form
the context object (we will see what that means later)

If the validate function returns anything beside of undefined the validated field will be marked as invalid. Also the return value will be the error:

const formConfig = createForm<RegistrationForm>()({
  username: field.text("user0"),
  dateOfBirth: field.datePicker(),
  password: field.password().validateOnSubmitOnly()
}).withValidation({
  // ...
  password: (value, values, context) => {
     if(!value) return "password is mandatory";
     if(!value.length < 8) return "password must be 8 characters long";
  }
})

We could possibly return very complex objects here to add more details to the error itself (and it will be typesafe!).

If we return a yup schema though, it will be a special case:

const formConfig = createForm<RegistrationForm>()({
  username: field.text("user0"),
  dateOfBirth: field.datePicker(),
  password: field.password().validateOnSubmitOnly()
}).withValidation({
  // ...
  // we just destructured username from values object so it looks a bit cleaner!
  password: (value, { username }, context) => {
     if(username && value.includes(username)){
       /**
        * It's an array since yup schema below will
        * also result in a error of type string[]
        * So it's easier to handle errors 
        * if they all have the same type
        */
       return ["password can't contain username"];
     } else {
       return yup.string().required().min(8);
     }
  }
})

I think you already know what's happening here. When we return a yup schema in a validate function it will not be treated as the error type, it will evaluate the the schema instead, so the error type will be string[]. And we actually just implemented conditional validation! Password is now validated based on the username field.

But whats about fields outside of the form? That's exactly why we have validation context. The initial context can be set via config while you can adapt the context at any time with setContext returned by useFluentForm.
The validation context needs to be any object, so it can not be a plain number or a string.

Let's assume that we have a country select which is outside of our registration form. The current country will be passed to the RegistrationForm component via props. Dependent on the selected country the minimum age for the Date of Birth field will vary (for USA 16, for the rest 18):

interface RegistrationFormProps {
  country: string;
}

const formConfig = createForm<RegistrationForm>()({
  /* fields.. */}
).withContext({
  country: "USA",
})

const RegistrationForm: React.FC<RegistrationFormProps> = ({country}) => {
  const { setContext } = useFluentForm(formConfig);

  useEffect(() => setContext({ country }), [country]);

  //...
}

As we can see it's pretty easy to update the context when it changes with useEffect. Now we can implement conditional validation based on the current context value:

// using validate function 
formConfing.withValidation({
  dateOfBirth: (value, values, { country }) => {
    if (country === "USA") {
      return yup.date().required().max(yearsBack16, "you must be at least 16");
    } else {
      return yup.date().required().max(yearsBack18, "you must be at least 18");
    }
  }
});

// using yup
formConfing.withValidation({
  dateOfBirth: yup.date().when("$country", {
    is: "USA",
    then: yup.date().required().max(yearsBack16, "you must be at least 16"),
    otherwise: yup.date().required().max(yearsBack18, "you must be at least 18")
  })
});

For customization of the validator please have a look at official react-fluent-form docs.

Play around and see how it works!

Following code sandbox contains the implementation of the previous examples in typescript! Just check it out:

If you are not clear with something or you want to know about other features like form arrays just checkout the official react-fluent-form docs

Conclusion

There a lot of form libraries out there and I simply tried to put all the good approached I observed so far in one library. You saw the things through my eyes and I'm sure you will totally agree on some points, but also totally disagree on others. And that's okay! I'm always open for constructive feedback, so feel free to add suggestions in the comments, or maybe better, file an issue or improvement on GitHub!

Every contribution is welcome!