DEV Community: Thomas Heniart

🤝 Strategy pattern at the service of SOLID Open-Closed principle

Thomas Heniart — Tue, 13 Feb 2024 12:00:00 +0000

Strategy pattern at the service of SOLID Open-Closed principle

The strategy pattern is a behavioral design pattern that allows you to define a family of algorithms that adhere to the
same contract, enabling the program to select the appropriate one at runtime. I won't delve into the details here, as
there are plenty of great contents available on the internet, such as https://refactoring.guru/design-patterns/strategy.
Instead, I'll demonstrate how to integrate it into your codebase to make it more extensible and compliant with the
Open-Closed principle of programming.

Consider an application feature where users can retrieve a list of animals in their country or any other country through
an input. To accomplish this, we've collaborated with a scientific lab that has gathered all the data for each animal
and provides us with an API with the following type of response.

[
    {
        id: "animalId1",
        name: "Ameiva martinicensis",
        locations: ["MQ"],
    },
    {
        id: "animalId2",
        name: "Oryctolagus cuniculus",
        locations: ["EU"],
    },
    {
        id: "animalId3",
        name: "Passer domesticus",
        locations: ["001"],
    },
    {
        id: "animalId4",
        name: "Canis lupus",
        locations: ["FX", "MQ"],
    },
]

However, there's one small issue: our application only supports
a portion of standard ISO 3166 Country Codes like US, FR, ES, UK,
etc..., while the API uses an extended version of these codes. For example, EU represents Europe, 001 signifies the
whole world, and MQ stands for Martinique, which is a French territory outside the mainland.

Our developers team quickly came up with a solution for this animal listing feature. (We assume some tests are covering
the feature behaviour of course)

class ListAnimal {
    constructor(private readonly _animalAPIGateway: AnimalAPIGateway) {
    }

    execute({country}: { country: Country }): Array<Animal> {
        const apiResponse = this._animalAPIGateway.listAll();
        return apiResponse
            .filter((a) => this.countryHasAnimal(country, a))
            .map((a) => ({name: a.name}));
    }

    private readonly countryHasAnimal = (
        country: Country,
        animal: AnimalResponseItem,
    ) => {
        if (country === "FR")
            return (
                animal.locations.includes("001") ||
                animal.locations.includes("EU") ||
                animal.locations.includes("FX")
            ); // etc...
        // Same logic for other countries
        return false; // We could also throw an exception but this is not the purpose of this article
    };
}

type Country = "FR" | "UK" | "US" | "ES";

type Animal = { name: string };

interface AnimalAPIGateway {
    listAll(): AnimalResponse;
}

type AnimalResponse = Array<AnimalResponseItem>;

type AnimalResponseItem = {
    id: string;
    name: string;
    locations: Array<string>;
};

You've probably already noticed that the countryHasAnimal method contains most of the logic for this feature. The main
issue with this method is that each time we introduce a new country into our application (which is growing rapidly), we
have to modify the codebase of the ListAnimal class, thus violating the Open-Closed principle.

Now that we've identified this violation, let's analyze this piece of code and consider what solution we can devise to
rectify it. After some deliberation, here's what we've concluded:

Each country's logic resides in an IF block.
Each block only requires the AnimalResponseItem.

These observations lead us to consider using a Map data structure that would have a function filtering an
AnimalResponseItem for each country our application supports.

First, let's introduce this typing:

type CountryFilters = Record<Country, CountryFilter>
type CountryFilter = (animal: AnimalResponseItem) => boolean;

Next, we can extract the logic into an external constant, for example, to ensure it doesn't disrupt our application's
test suite.

export const countryFilters: CountryFilters = {
    FR: (animal) =>
        animal.locations.includes("001") ||
        animal.locations.includes("EU") ||
        animal.locations.includes("MQ") ||
        animal.locations.includes("FX"),
    //US: (animal) => US LOGIC, etc...
};

Then, let's replace the code of countryHasAnimal with a call to our countryFilters constant.

class ListAnimal {
    private readonly countryHasAnimal = (
        country: Country,
        animal: AnimalResponseItem,
    ) => {
        return countryFilters[country](animal)
    };
}

We can even refactor it further by introducing some syntactic sugar, resulting in a straightforward implementation of
our feature.

class ListAnimal {
    constructor(private readonly _animalAPIGateway: AnimalAPIGateway) {
    }

    execute({country}: { country: Country }): Array<Animal> {
        const apiResponse = this._animalAPIGateway.listAll();
        return apiResponse
            .filter(countryFilters[country])
            .map((a) => ({name: a.name}));
    }
}

And there you have it! Our code no longer violates the Open-Closed principle because introducing a new country into our
system only requires adding a new filter to the countryFilters, which is considered an extension.

We won't need to touch our ListAnimal feature at all! Beautiful, isn't it?

Stay tuned for more insights! Free to follow me on this platform
and LinkedIn. I share insights every week about software
design, OOP practices, and some personal project discoveries! 💻🏄

The Liskov Substitution Principle Demystified

Thomas Heniart — Tue, 06 Feb 2024 12:00:00 +0000

The Liskov Substitution Principle (LSP) is a fundamental concept in object-oriented programming (OOP) introduced by
Barbara Liskov in 1987. You probably know it as the L in the five SOLID
principles.

According to the LSP, objects of a superclass should seamlessly replace objects of its subclasses without affecting the
program's correctness. In simpler terms, if S is a subtype of T, then objects of type T can be substituted with objects
of type S without altering the program's desirable properties.

Practically, violating the Liskov Substitution Principle can result in unexpected behavior, increased code complexity,
and difficulties in future maintenance and extension. Therefore, it's crucial for developers to meticulously design
their class hierarchies, ensuring that subtypes are genuine extensions of their supertypes and can be effortlessly
substituted wherever the supertype is employed.

Consider an example using a traditional interpretation of ducks in a program and the introduction of a robot duck that
violates the Liskov Substitution Principle.

Suppose we have a class hierarchy for ducks:

abstract class Duck {
    abstract quack(): void;

    abstract fly(): void;
}

class MallardDuck extends Duck {
    quack(): void {
        console.log("Quack")
    }

    fly(): void {
        console.log("To Infinity, And Beyond!")
    }
}

class RobotDuck extends Duck {
    quack(): void {
        console.log("Beep beep")
    }

    fly(): void {
        throw new MethodShouldNotBeImplementedException("Robot ducks can't fly")
    }
}

In this scenario, the Liskov Substitution Principle is violated with the RobotDuck class. Although it extends the Duck
class and looks like a duck, it doesn't behave like one. According to LSP, objects of a subclass should be substitutable
for objects of the superclass without altering the program's correctness.

The issue arises when trying to use a RobotDuck object in a context where a Duck object is expected, for example:

const makeDuckFly = (duck: Duck) => {
    duck.fly()
}

const mallard = new MallardDuck()
const robotDuck = new RobotDuck()

makeDuckFly(mallard)  // This works fine
makeDuckFly(robotDuck) // Throws MethodShouldNotBeImplementedException

On a daily basis, it's crucial to be aware that whenever you override a method in your superclass (or interface) to
throw an exception because this method doesn't make sense for your current type, take a step back and analyze your
codebase to identify problems in your design.

Concerning the previous example, you can redesign the hierarchy and introduce interfaces, allowing MallardDuck and
RobotDuck to share their common trait through a Quackable interface. MallardDuck can then implement a Flying interface
for its flying ability.

interface Quackable {
    quack(): void;
}

interface Flying {
    fly(): void;
}

class MallardDuck implements Quackable, Flying {
    quack(): void {
        console.log("Quack")
    }

    fly(): void {
        console.log("To Infinity, And Beyond!")
    }
}

class RobotDuck implements Quackable {
    quack(): void {
        console.log("Beep beep")
    }
}

By doing so, you can easily add a Goose that shares common properties with a MallardDuck without being a Duck, which was
not possible in the previous hierarchy solely focused on Ducks.

class Goose implements Quackable, Flying {
    quack(): void {
        console.log("Quaaaack")
    }

    fly(): void {
        console.log("To Infinity, And Beyond!")
    }
}

Stay tuned for more insights! Free to follow me on this platform
and LinkedIn. I share insights every week about software
design, OOP practices, and some personal project discoveries! 💻🏄

Decoding the Law of Demeter through Real-World Example

Thomas Heniart — Tue, 30 Jan 2024 12:00:00 +0000

Have you ever heard of the Law of Demeter? Do you know if you are violating it?

Let's dive into a real-world example: I am looking for "Test Driven Development By Example," and I know that one of my
friends (let's call him John) told me about one of his other friends (whom I don't know yet) who found a second-hand
example.
I would directly ask John to inquire where he bought it.

It would be counterproductive to ask John to meet his friend and then ask him about it.

My only interest is in John being able to find the information I am looking for.
He may even already know the answer, but I need to know.

If you are familiar with OOP, it should ring a bell and make you think about one of the most fundamental rules of OOP:
Tell, don't ask.

Stay tuned for more insights! Free to follow me on this platform
and LinkedIn. I share insights every week about software
design, OOP practices, and some personal project discoveries! 💻🏄

OOP Fundamentals: Tell 📣, don't ask 🚫

Thomas Heniart — Tue, 23 Jan 2024 12:00:00 +0000

Are you still stuck in the habit of using getters and setters in your code? Well, you've landed on the right page to
grasp one of the most fundamental concepts of Object-Oriented Programming!

Rethinking Object-Oriented Development

Often, developers mistakenly believe they are practicing Object-Oriented Programming (OOP) simply by employing
service-like classes. The example below is a common scenario encountered across various projects:

class IncreaseBankAccountBalance {
    constructor(private readonly _bankAccountRepository: BankAccountRepository) {
    }

    execute({id, increase}: { id: string, increase: number }) {
        const account = this._bankAccountRepository.findById(id)
        const currentBalance = account.getBalance()
        const newBalance = currentBalance + increase
        account.setBalance(newBalance)
        this._bankAccountRepository.save(account)
    }
}

class BankAccount {
    constructor(
        private readonly _id: number,
        private _balance: number
    ) {
    }

    getBalance() {
        return this._balance
    }

    setBalance(value: number) {
        this._balance = value;
    }
}

In this scenario, we fetch an account from a repository and then proceed to call getters and setters to update it. It's
akin to treating a private property like a public one, exposing its value and providing a method to modify it at the
user's discretion.

Unveiling the Object-Oriented Approach

The core principle of OOP is to tell instances to perform work rather than manipulating their properties directly.
This encapsulation of logic within domain entities, rather than imperative services, defines true OOP.

Refining our example, we can shift the increase logic from the IncreaseBankAccountBalance service to the BankAccount
class through a well-named instance method:

class IncreaseBankAccountBalance {
    constructor(private readonly _bankAccountRepository: BankAccountRepository) {
    }

    execute({id, increase}: { id: string, increase: number }) {
        const account = this._bankAccountRepository.findById(id)
        account.increaseBalance(increase)
        this._bankAccountRepository.save(account)
    }
}

class BankAccount {
    constructor(
        private readonly _id: number,
        private _balance: number
    ) {
    }

    increaseBalance(increase: number) {
        this._balance += increase;
    }
}

Now, notice that we no longer expose the private balance property. Any user of the BankAccount class must go through
the
increaseBalance instance method, effectively encapsulating the logic of balance increase.

Elevating Immutability for Code Integrity

As a bonus, we can take it a step further by introducing immutability to our code. This minimizes side effects by
returning a new instance of BankAccount with the updated balance, instead of modifying its private property directly:

class IncreaseBankAccountBalance {
    constructor(private readonly _bankAccountRepository: BankAccountRepository) {
    }

    execute({id, increase}: { id: string, increase: number }) {
        const account = this._bankAccountRepository.findById(id)
        this._bankAccountRepository.save(account.withIncreasedBalance(increase))
    }
}

class BankAccount {
    constructor(
        private readonly _id: number,
        private readonly _balance: number
    ) {
    }

    withIncreasedBalance(increase: number) {
        return new BankAccount(this._id, this._balance + increase)
    }
}

In summary, here are some key takeaways for your future coding sessions:

Be cautious when exposing getters and especially when exposing a setter.
Objects should be the sole entities allowed to modify their properties.
Every method must be well-named, clearly expressing its intent.

Stay tuned for more insights! Free to follow me on this platform
and LinkedIn. I share insights every week about software
design, OOP practices, and some personal project discoveries! 💻🏄

Test Doubles: A Quick Guide to Boost Your Testing Skills

Thomas Heniart — Tue, 16 Jan 2024 12:00:00 +0000

Welcome to the fast-paced realm of software development, where mastering Test Doubles is your key to crafting rock-solid
code and easing your way to TDD mastery. In just a few seconds, we'll unravel the secrets of spies, stubs, and fakes,
exploring their power to supercharge your testing game. Whether you're a TDD veteran or a newcomer, join us on this
quick journey to transform your approach to testing and elevate our code quality.

Doubles come into play when you prefer not to employ a specific implementation of an interface in your tests,
streamlining the test-writing process and speeding up feedback on actual features. They prove valuable in ensuring test
independence from infrastructure, such as crafting Doubles for a Repository and contributing to more effective and
efficient testing.

Dummy

Dummies are services that our SUT (System Under Test) depends on but are irrelevant to the test scope.

Example with a banking account creation feature relying on a BankingAccountRepository as well as an EventPublisher and
our current tests do not have any concern for the event publisher. We can just replace it with a Dummy implementation
that will not affect our testing system.

class CreateBankingAccount {
    constructor(
        private readonly _bankingAccountRepository: BankingAccountRepository,
        private readonly _eventPublisher: EventPublisher
    ) {
    }

    execute() {
        //Some business logic and references to _eventPublisher
    }
}

interface EventPublisher {
    publish(event: Event): void
}

class DummyEventPublisher implements EventPublisher {
    publish(event: Event): void {
        // Do nothing, we call it a dummy implementation
    }
}

Spy

A test spy is a tool that captures indirect output and provides necessary indirect input, dealing with output that is
not directly observable.

In the given code snippet, we obtain detailed information about "published" events. This is especially valuable in an
event-driven system where you need or must publish events on a bus without yet knowing the subsequent actions they may
trigger.

The key motivation behind employing a spy is to gain a more in-depth insight into the internal state of the system, even
though this comes at the expense of heightened coupling.

it("publishes a banking account event", () => {
    const spy = new SpyEventPublisher();
    const useCase = new CreateBankingAccount(bankingAccountRepository, spy);

    useCase.execute();

    expect(spy.events.length).toEqual(1);
    expect(spy.events[0]).toEqual({id: "newBankingAccountId"});
})

class SpyEventPublisher implements EventPublisher {
    private readonly _events: Array<Event> = []

    publish(event: Event): void {
        this._events.push(event)
    }

    get events() {
        return this._events
    }
}

class CreateBankingAccount {
    constructor(
        private readonly _bankingAccountRepository: BankingAccountRepository,
        private readonly _eventPublisher: EventPublisher
    ) {
    }

    execute() {
        //Some business logic
        this._eventPublisher.publish({id: "newBankingAccountId"})
    }
}

Stub

A stub is an object that returns fake data injected into it.

Consider a scenario where our feature relies on an external API to fetch user data, such as a credit score needed for
creating an account. To ensure the service functions as expected, we can build a stub object with fake values.

The following snippet represents a potential implementation of a stub for the external API.

interface UserDataGateway {
    creditScore(email: string): number
}

class StubUserDataGateway implements UserDataGateway {
    private _creditScoreValue: number

    creditScore(email: string): number {
        return this._creditScoreValue;
    }

    set creditScoreValue(value: number) {
        this._creditScoreValue = value;
    }
}

Then our test would look like:

it("requires a positive credit score to create a bank account", async () => {
    const stub = new StubUserDataGateway();
    const useCase = new CreateBankingAccount(bankingAccountRepository, new DummyEventPublisher());
    {
        stub.creditScoreValue = 0
        useCase.execute({email: "john@doe.com"});
        expect(bankingAccountRepository.accounts).toEqual([]);
    }
    {
        stub.creditScoreValue = 20
        useCase.execute({email: "jane@doe.com"});
        expect(bankingAccountRepository.accounts).toEqual([/*An account object*/]);
    }
})

class CreateBankingAccount {
    constructor(
        private readonly _bankingAccountRepository: BankingAccountRepository,
        private readonly _userDataGateway: UserDataGateway
    ) {
    }

    execute({email}: { email: string }) {
        if (!this._userDataGateway.creditScore(email)) return
        // Bank account creation logic
    }
}

I'm confident you've already noticed a flaw in this design. The issue lies in the fact that we could replace the email
with any string in the statement below, because of our Stub implementation.

this._userDataGateway.creditScore(email)

This is why, most of the time, we prefer to add a touch of simple logic rather than keeping it entirely straightforward,
as you can see in the following code snippet.

class StubUserDataGateway implements UserDataGateway {
    private _creditScores: { [email: string]: number } = {}

    creditScore(email: string): number {
        return this._creditScores[email] || 0;
    }

    feedWith(email, creditScore) {
        this._creditScores[email] = creditScore;
    }
}

Leading our test implementation to

it("requires a positive credit score to create a bank account", async () => {
    const stub = new StubUserDataGateway();
    const useCase = new CreateBankingAccount(bankingAccountRepository, new DummyEventPublisher());
    {
        stub.feedWith("john@doe.com", 0)
        useCase.execute({email: "john@doe.com"});
        expect(bankingAccountRepository.accounts).toEqual([]);
    }
    {
        stub.feedWith("jane@doe.com", 1)
        useCase.execute({email: "jane@doe.com"});
        expect(bankingAccountRepository.accounts).toEqual([/*An account object*/]);
    }
})

Fake

Last but not least, Fakes! They are primarily used when we want to implement an architectural interface with some
in-memory logic, so we are not bound to an external infrastructure service like a Database for example. Depending on its
implementation, but most of the time, a fake implementation can be used in a production-like environment for demo
purposes.

The following snippet represents a simple but common Fake implementation of a repository in a trivial system:

class InMemoryBankingAccountRepository implements BankingAccountRepository {
    private readonly _accounts: Array<BankingAccount> = []

    create(bankingAccount: BankingAccount) {
        this._accounts.push(bankingAccount)
    }


    get accounts(): Array<BankingAccount> {
        return this._accounts;
    }
}


it("creates an account", async () => {
    const repository = new InMemoryBankingAccountRepository()
    const useCase = new CreateBankingAccount(bankingAccountRepository)

    useCase.execute({accountId: "someAccountId"})

    expect(repository.accounts).toEqual([{accountId: "someAccountId"}])
})

In future articles, we will dive deeper into these concepts and apply them in real-world applications.

Stay tuned, and feel free to follow me on this platform and
on LinkedIn, where I share insights every week about software
design, OOP practices, discoveries, and my projects! 💻🏄

Quickly build a React Native Project on TestFlight

Thomas Heniart — Thu, 16 Nov 2023 21:59:39 +0000

This tutorial aims to guide you through the process of setting up a React Native app and distributing a build on TestFlight for your beta testers. The primary objective is to reduce the time spent on iOS app building and simplify the gathering of valuable feedback from your beta testers. By following the instructions provided in this tutorial, you will be able to swiftly deploy your app on TestFlight and effectively collect feedback to enhance your app prior to its official release.

Create your react native project

To get started, it's important to first follow the instructions provided at https://reactnative.dev/docs/environment-setup. These instructions will guide you through the process of setting up your environment and ensuring that you have all the necessary requirements in place before diving into the project.

npm uninstall -g react-native-cli @react-native-community/cli
npx react-native@latest init AwesomeProject
cd AwesomeProject

To verify that your app is working on your simulator, follow the steps outlined in this link.

Setup fastlane for your project

Fastlane is an open-source platform designed to simplify Android and iOS deployment. It allows you to automate every aspect of your development and release workflow.

Installation

xcode-select --install
brew install fastlane

Prerequisites

Before proceeding, please make sure that you fulfill the following criteria:

Install all required dependencies, with Xcode 9 or higher
Choose the bundle identifier for your app. For the purposes of the following steps, I will use org.awesome.AwesomeProject.
An Apple ID with an admin or developer user, with its username (email, for example dev-team@yourcompany.com) and password
An App-Specific Password : Go to https://appleid.apple.com/account/manage, login, and then go to App-Specific Passwords, from here, generate a new App-Specific Password and copy it (keep it safe)
Your app name, Fastlane will automatically create your application in the Developer Portal and App Store
Another Git repository associated with this project. It will be utilized to store the fastlane match configuration.

Use below right .gitignore inside the ios directory

# fastlane env
fastlane/.env

# fastlane specific
fastlane/report.xml

# deliver temporary files
fastlane/Preview.html

# snapshot generated screenshots
fastlane/screenshots

# scan temporary files
fastlane/test_output

# fastlane builds
builds/*
*.xcarchive

You also need to create an App Icon to use Fastlane or you will get an error on running fastlane beta. You can simply create one using the website MakeAppIcon and follow this tutorial to configure it properly.

Open your Xcode project (double click on AwesomeProject.xcodeproj) and modify some information:

In the General tab, Identity section, change the Bundle Identifier to your identifier (useful for Fastlane)
In the Signing & Capabilities tab, Signing section, disable Automatically manage signing
In the Build Settings tab, set view filter on top to All and Combined, then go to the Signing section and into Code Signing Identity, set Apple Development for the debug line (including Any iOS SDK also) and set Apple Distribution for the release line (including Any iOS SDK also).

Like this:

Code Signing Identity	< Multiple values >
Debug	Apple Development
Any iOS SDK	Apple Development
Release	Apple Distribution
Any iOS SDK	Apple Distribution

Setup

Init

cd ios
fastlane init

Fastlane will autonomously identify your project and prompt you for any missing details.

When prompted with the question, "What would you like to use Fastlane for?" select option 2, which is "Automate beta distribution to TestFlight.”

Signing and certificates

fastlane match init

You will be prompted to specify a Git repository. Supply the previously created repository dedicated to configuration storage for this purpose.

Now, let's dive into the sanitation and generation of your Apple ID certificates using the commands provided below.

fastlane match nuke development
fastlane match nuke distribution
fastlane match nuke enterprise

fastlane match appstore
fastlane match development
fastlane match adhoc

Then, make some adjustments to the files generated in the init step to include the signing configuration

AwesomeProject/ios/fastlane/Fastfile

# This file contains the fastlane.tools configuration
# You can find the documentation at https://docs.fastlane.tools
#
# For a list of all available actions, check out
#
#     https://docs.fastlane.tools/actions
#
# For a list of all available plugins, check out
#
#     https://docs.fastlane.tools/plugins/available-plugins
#

# Uncomment the line if you want fastlane to automatically update itself
# update_fastlane

default_platform(:ios)

platform :ios do
  desc "Push a new beta build to TestFlight"
  lane :beta do
    increment_build_number(xcodeproj: "AwesomeProject.xcodeproj") # Path to xcodeproj
    get_certificates( # Create or get certificate, and install it
      output_path: "./builds" # Download certificate in the build folder (you don't need to create the folder)
    )
    get_provisioning_profile( # Create or get provisioning profile
      output_path: "./builds",  # Download provisioning profile in the build folder
      filename: "provisioning.mobileprovision" # Rename the local provisioning profile
    )
    update_project_provisioning( # Set the project provisioning profile (related in Xcode to the General > Signing Release section)
      xcodeproj: "AwesomeProject.xcodeproj", # Path to xcodeproj
      target_filter: "AwesomeProject", # Name of your project
      profile: "./builds/provisioning.mobileprovision",
      build_configuration: "Release"
    )
    update_project_team( # Set the right team on your project
      teamid: CredentialsManager::AppfileConfig.try_fetch_value(:team_id)
    )
    build_app(
      workspace: "YeetipMobile.xcworkspace",
      scheme: "YeetipMobile",
      clean: true,
      export_method: "app-store",
      export_options: {
        provisioningProfiles: {
            CredentialsManager::AppfileConfig.try_fetch_value(:app_identifier) => CredentialsManager::AppfileConfig.try_fetch_value(:app_identifier) + " AppStore" # Value of this parameter is the name of the Provisioning Profile. By default, it will be "{bundleId} AppStore"
        }
      },
      build_path: "./builds",
      output_directory: "./builds"
    )
    changelog_from_git_commits
    upload_to_testflight
  end
end

AwesomeProject/ios/fastlane/.env

FASTLANE_USER=<AppleID>
FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD=<App-Specific Password>

Build for TestFlight

It's time to build! Simply execute below command in the ios folder (it might take a few minutes).

fastlane beta

After your beta build is published on TestFlight, navigate to https://appstoreconnect.apple.com/apps > AwesomeProject > TestFlight to confirm your build has been shipped successfully.

Integration testing with Jest and PostgreSQL

Thomas Heniart — Sat, 20 May 2023 06:20:00 +0000

One of the crucial tasks of a developer is to write integration tests for the database to ensure that the implementation is performing as expected. However, running integration tests independently and concurrently against a shared database can lead to tests interfering with one another and failing intermittently. All code samples are in TypeScript, but the same logic applies to any other language.

Problem

The problem arises when integration tests suites run concurrently against a shared database instance. For instance, given a simple implementation of an SQL repository using ts-postgres library and Jest test suites provided in the code blocks, you can run jest a couple of times and experience the concurrency problem. The issue stems from the database being emptied between the await repository.insert(id); and expect(await repository.findAll()).toEqual([[id]]); statements, due to the fact that the selects nothing test finishes and deletes table records just before the expect statement.

src/exampleRepository.ts

import { Client, Value } from "ts-postgres";

export class ExampleRepository {
  private readonly _client: Client;

  constructor(client: Client) {
    this._client = client;
  }

  async findAll(): Promise<Array<Value>> {
    return (await this._client.query("SELECT * FROM example")).rows;
  }

  async insert(id: string): Promise<void> {
    await this._client.query("INSERT INTO example (id) VALUES ($1)", [id]);
  }
}

src/test/problematic/insert.test.ts

import { Client } from "ts-postgres";
import { ExampleRepository } from "../../exampleRepository";
import { config } from "dotenv";
import { v4 } from "uuid";
import { rootConnect } from "../postgresUtils";

describe("Insert Test Suite", () => {
  let client: Client;
  let repository: ExampleRepository;

  beforeAll(async () => {
    config();
    client = await rootConnect();
  });

  afterAll(async () => {
    await client.end();
  });

  beforeEach(() => {
    repository = new ExampleRepository(client);
  });

  afterEach(async () => {
    await client.query("DELETE FROM example");
  });

  it("inserts and select", async () => {
    const id = v4();
    await repository.insert(id);
    expect(await repository.findAll()).toEqual([[id]]);
  });
});

src/test/problematic/select.test.ts

import { Client } from "ts-postgres";
import { ExampleRepository } from "../../exampleRepository";
import { config } from "dotenv";
import { rootConnect } from "../postgresUtils";

describe("Select Test Suite", () => {
  let client: Client;
  let repository: ExampleRepository;

  beforeAll(async () => {
    config();
    client = await rootConnect();
  });

  afterAll(async () => {
    await client.end();
  });

  beforeEach(() => {
    repository = new ExampleRepository(client);
  });

  afterEach(async () => {
    await client.query("DELETE FROM example");
  });

  it("selects nothing", async () => {
    expect(await repository.findAll()).toEqual([]);
  });
});

src/test/postgreUtils.ts

export const rootConnect = async () => connectToDatabase(process.env.DB_NAME);

const connectToDatabase = async (database: string) => {
  const client = new Client({
    host: process.env.DB_HOST,
    port: parseInt(process.env.DB_PORT),
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database,
    ssl: SSLMode.Disable,
  });

  await client.connect();
  return client;
};

Solution

While we could specify --maxWorkers=1 to jest, this would drastically increase our tests' duration. A better approach would be to enable reliable, isolated integration testing, by ensuring that each test suite runs against a separate, isolated database instance. To achieve this, we can create a freshly new database during the beforeAll function.

Assuming that your test suite is in a folder src/__test__ and SQL scripts needed to set up your database tables are in src/sql, the solution is as easy as using the root connection to create a new database with a UUID name and then using that connection to run SQL migration scripts. To achieve this, we can create a simple helper that will allow us to call only one function in our test suites. The modified code is shown below.

src/test/postgreUtils.ts

import { Client, SSLMode } from "ts-postgres";
import { v4 as uuid } from "uuid";
import { readdirSync, readFileSync } from "fs";

export const connectToTestDatabase = async () => {
  let client = await rootConnect();
  const database = uuid();
  await client.query(`CREATE DATABASE "${database}"`);
  await client.end();
  client = await connectToDatabase(database);
  await runMigrations(client);
  return client;
};

export const rootConnect = async () => connectToDatabase(process.env.DB_NAME);

const connectToDatabase = async (database: string) => {
  const client = new Client({
    host: process.env.DB_HOST,
    port: parseInt(process.env.DB_PORT),
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database,
    ssl: SSLMode.Disable,
  });

  await client.connect();
  return client;
};

const runMigrations = async (client: Client) => {
  const migrationsPath = `${__dirname}/../../sql`;
  for (const filePath of readdirSync(migrationsPath))
    await runMigration(client, `${migrationsPath}/${filePath}`);
};

const runMigration = async (client: Client, filePath) => {
  for (const query of queriesInMigrationFile(filePath))
    await client.query(query);
};

/**
 * :warning: - Fails if a query inserts data containing ";" character
 * @param filePath
 */
const queriesInMigrationFile = (filePath: string) =>
  readFileSync(filePath).toString().split(";");

By making use of the above helper functions, you can ensure that each test suite runs against its own database instance, avoiding concurrency issues and enabling reliable, isolated integration testing.

Optimizing Migrations with PostgreSQL Client

In order to enhance the performance of running migrations, we can leverage the use of a PostgreSQL client. While the previous solution involving custom parsing of SQL files might works just fine for you, a client like PostgreSQL can offer better efficiency and will support migrations involving TRIGGERS for example.

To get started, simply install a PostgreSQL client by following the instructions below depending on your operating system:

For OS X, run brew install libpq && brew link --force libpq
For Ubuntu/Debian, run sudo apt install postgresql-client

Verify the installation by running psql --version

Next, we can slightly modify our runMigrations helper function to execute each migration file using the PostgreSQL client configuration. The code snippet for this is shown below:

export const runMigrations: async (client: Client) => {
  for (const filePath of readdirSync(migrationsPath))
    child_process.execSync(
      `PGPASSWORD="${client.config.password}" psql -h ${client.config.host} -p ${client.config.port} -U ${client.config.user} -d ${client.config.database} -a -f ${migrationsPath}/${filePath}`
    );
};

Bonus: Continuous Integration (CI)

To conclude this article, I would like to provide you with two examples of CI jobs utilizing a PostgreSQL database service, thus automating your tests on a CI/CD pipeline.

With gitlab-ci (.gitlab-ci.yml)

stages:
  - test

integration-tests:
  stage: test
  image: node:18.14.0
  services:
    - name: postgres:15.2
      alias: postgres
  variables:
    POSTGRES_DB: jest-psql-example
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: example
    POSTGRES_HOST_AUTH_METHOD: trust
    DB_HOST: "postgres"
    DB_PORT: "5432"
    DB_USER: "postgres"
    DB_PASSWORD: "example"
    DB_NAME: "my-database"
  before_script:
    - apt-get update && apt-get install -y postgresql-client
    - yarn
    - for f in ./sql/*.sql; do psql -h ${DB_HOST} -U ${DB_USER} -d ${DB_NAME} -a -f $f > /dev/null; done
  script:
    - jest

With github workflow (.github/worflows/test.yaml)

name: test
on: [ push ]
jobs:
  integration-tests:
    runs-on: ubuntu-latest
    container: node:18.14
    services:
      postgres:
        image: postgres:15.2
        env:
          POSTGRES_DB: jest-psql-example
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: example
          POSTGRES_HOST_AUTH_METHOD: trust
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g yarn
      - run: yarn
      - name: Run migrations
        env:
          DB_HOST: "postgres"
          DB_USER: "postgres"
          PGPASSWORD: "example"
          DB_NAME: "my-database"
        run: |
          apt-get update
          apt-get install --yes postgresql-client
          for f in ./sql/*.sql; do psql -h ${DB_HOST} -U ${DB_USER} -d ${DB_NAME} -a -f $f > /dev/null; done
      - name: Run integration tests
        env:
          DB_HOST: "postgres"
          DB_PORT: "5432"
          DB_USER: "postgres"
          DB_PASSWORD: "example"
          DB_NAME: "jest-psql-example"
        run: jest

All code samples are available on Jest-PostgresSQL-Integration-Testing repository