Setting Up Local Supabase Database Testing

Testing your Supabase database shouldn't require deploying to the cloud or sharing a development database. With supabase-test and @pgpm/supabase, you get instant, isolated Postgres databases that mirror your Supabase environment—perfect for fast, reliable tests.

Prerequisites

See Prerequisites.

Install pgpm

npm i -g pgpm

Installs the pgpm command globally so you can use it anywhere. If your shell cannot find pgpm after install, open a new terminal or add the npm global bin to your PATH.

Create a Workspace for Your Supabase Project

Create a pgpm workspace to organize your Supabase project:

pgpm init workspace

When prompted, enter your workspace name:

? Enter workspace name: my-supabase-project

Install dependencies:

cd my-supabase-project
pnpm install

Create a Module for Your Supabase Testing

Create a pgpm module to organize your Supabase database code:

pgpm init

Enter module details when prompted:

? Enter module name: my-supabase-app
? Select extensions (use arrow keys and space to select):
  ◉ plpgsql
  ◉ uuid-ossp

Install Supabase Testing Dependencies

Install supabase-test in your module:

cd packages/my-supabase-app
pnpm add -D supabase-test

The supabase-test package is built on top of pgsql-test with Supabase defaults baked in. It automatically configures connection settings for the local Supabase stack.

Install the Supabase testing harness via pgpm (not pnpm):

pgpm install @pgpm/supabase

This installs the @pgpm/supabase package, which provides Supabase's auth schema and other core modules. This allows you to import Supabase schemas into your temporary test databases, giving you a complete Supabase environment for testing.

Install Supabase CLI and Start Local Stack

Initialize Supabase in your workspace (from the module directory):

npx supabase init

Start the local Supabase stack:

npx supabase start

This provisions a complete Supabase environment locally, including Postgres, Auth, Storage, and all system schemas. Note the connection details—you'll need the database port (typically 54322).

What You've Accomplished

You now have a complete Supabase testing environment:

• pgpm workspace organized for your Supabase project
• Local Supabase stack running with all system schemas
• supabase-test configured for instant, isolated test databases
• @pgpm/supabase testing harness

Next, you'll learn how to write your first supabase test using TypeScript.