supabase-test is a specialized library designed to facilitate robust integration testing for Supabase projects by providing isolated, ephemeral PostgreSQL environments. It leverages Docker to spin up fresh, role-aware database instances for each test or test suite, ensuring complete data isolation and preventing test interference. As of its current stable version, 2.9.3, the library is actively maintained, receiving iterative updates for compatibility with the latest Supabase and PostgreSQL versions, and addressing new features or performance enhancements. Its key differentiators include built-in support for Row-Level Security (RLS) testing, allowing developers to rigorously validate their security policies, and a rollback-friendly architecture that simplifies test teardown, making it an essential tool for comprehensive Supabase backend testing.
npm install supabase-testVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to use `withTestDatabase` to create an isolated Supabase environment for integration tests, including user authentication, RLS-aware data manipulation, and preventing unauthorized access.
Review the official changelog and migration guides for your specific version upgrade (e.g., v1 to v2) and adjust `withTestDatabase` options and callback signatures accordingly.
Ensure Docker Desktop is running and healthy before executing tests. Check Docker logs for container startup issues. Consider increasing Docker's resource allocation if tests are consistently failing due to resource exhaustion.
Use `withTestDatabase` only for integration or end-to-end tests where a real database is truly necessary. For unit tests, mock database interactions. Consider using a single `withTestDatabase` instance per test *suite* (e.g., `describe` block) rather than per `test` block, leveraging its reset functionality, or using `setupDatabase` for global setup where appropriate to reduce overhead.
Thoroughly review your RLS policies, especially the `USING` and `WITH CHECK` clauses for different roles and operations. Write specific tests for RLS scenarios, including authenticated users, anonymous users, and different user roles, to ensure policies behave as expected.
Verify that Docker Desktop (or the Docker daemon) is running. Check if port 5432 is already in use by another application. Review Docker logs for errors related to the PostgreSQL container startup.
Double-check that the `migrationsPath` option in `withTestDatabase` points to the correct directory containing your Supabase SQL migration files. Manually verify the SQL syntax and order of your migration scripts.
Examine the RLS policies defined in your migrations for the `profiles` table. Ensure there is an `INSERT` policy that grants the necessary permissions to the roles you are testing with, especially for authenticated users. Make sure the policy's `WITH CHECK` clause allows the insert.
No dependency data recorded yet.