{"id":14063351,"url":"https://github.com/usebasejump/supabase-test-helpers","last_synced_at":"2025-10-25T15:37:35.689Z","repository":{"id":151825682,"uuid":"559627788","full_name":"usebasejump/supabase-test-helpers","owner":"usebasejump","description":"Test helpers for pgTAP and Supabase","archived":false,"fork":false,"pushed_at":"2024-05-15T01:22:25.000Z","size":92,"stargazers_count":95,"open_issues_count":5,"forks_count":12,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-13T07:04:43.509Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://usebasejump.com/blog/testing-on-supabase-with-pgtap","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usebasejump.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-30T17:44:18.000Z","updated_at":"2024-08-06T11:25:45.000Z","dependencies_parsed_at":"2023-05-12T00:30:20.614Z","dependency_job_id":"fa954126-493c-451b-943c-d398e159de74","html_url":"https://github.com/usebasejump/supabase-test-helpers","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usebasejump%2Fsupabase-test-helpers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usebasejump%2Fsupabase-test-helpers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usebasejump%2Fsupabase-test-helpers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usebasejump%2Fsupabase-test-helpers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usebasejump","download_url":"https://codeload.github.com/usebasejump/supabase-test-helpers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228028307,"owners_count":17858312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-13T07:03:17.627Z","updated_at":"2025-10-25T15:37:35.604Z","avatar_url":"https://github.com/usebasejump.png","language":"PLpgSQL","funding_links":[],"categories":["PLpgSQL"],"sub_categories":[],"readme":"# Supabase Test Helpers\nA collection of functions designed to make testing Supabase projects easier. Created as part of our [open source SaaS starter for Supabase](https://usebasejump.com).\n\n## Quick Start (recommended)\nIf you're using Supabase:\n\n1) Install dbdev following the instructions here: [github.com/supabase/dbdev](https://github.com/supabase/dbdev)\n2) Install the test helpers as an extension:\n\n```sql\nselect dbdev.install('basejump-supabase_test_helpers');\n```\n\nI don't recommend activating the extension in production directly, instead you can activate it as part of your test suite.  For example:\n\n```sql\nBEGIN;\nCREATE EXTENSION \"basejump-supabase_test_helpers\";\n\nselect plan(1);\n-- create a table, which will have RLS disabled by default\nCREATE TABLE public.tb1 (id int, data text);\nALTER TABLE public.tb1 ENABLE ROW LEVEL SECURITY;\n\n-- test to make sure RLS check works\nselect check_test(tests.rls_enabled('public', 'tb1'), true);\n\nSELECT * FROM finish();\nROLLBACK;\n```\n\nFor a basic example, check out the [example blog tests](https://github.com/usebasejump/supabase-test-helpers/blob/main/supabase/tests/99-blog-example.sql).\n\n## Manual Installation (not recommended)\nCopy the contents of the most recent version into the very first alphabetical test in your test suite, such as `00000-supabase_test_helpers.sql`. This will ensure that the test helpers are removed after your tests have run. for it to work, you need to create some fake tests at the bottom of the file for pgtap to not complain.  Here's an example:\n```sql\n\n-- we have to run some tests to get this to pass as the first test file.\n-- investigating options to make this better.  Maybe a dedicated test harness\n-- but we dont' want these functions to always exist on the database.\nBEGIN;\n\n    select plan(7);\n    select function_returns('tests', 'create_supabase_user', Array['text', 'text', 'text', 'jsonb'], 'uuid');\n    select function_returns('tests', 'get_supabase_uid', Array['text'], 'uuid');\n    select function_returns('tests', 'get_supabase_user', Array['text'], 'json');\n    select function_returns('tests', 'authenticate_as', Array['text'], 'void');\n    select function_returns('tests', 'clear_authentication', Array[null], 'void');\n    select function_returns('tests', 'rls_enabled', Array['text', 'text'], 'text');\n    select function_returns('tests', 'rls_enabled', Array['text'], 'text');\n    select * from finish();\nROLLBACK;\n```\n\n## Writing tests\nCheck out the docs below for available helpers. To view a comprehensive example, check out our [blog tests](https://github.com/usebasejump/supabase-test-helpers/blob/main/supabase/tests/99-blog-example.sql).\n\n## Test Helpers\nThe following is auto-generated off of comments in the `supabase_test_helpers--0.0.2.sql` file. Any changes added to the README directly will be overwritten.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n  - [tests.create_supabase_user(identifier text, email text, phone text)](#testscreate_supabase_useridentifier-text-email-text-phone-text)\n  - [tests.get_supabase_user(identifier text)](#testsget_supabase_useridentifier-text)\n  - [tests.get_supabase_uid(identifier text)](#testsget_supabase_uididentifier-text)\n  - [tests.authenticate_as(identifier text)](#testsauthenticate_asidentifier-text)\n  - [tests.authenticate_as_service_role()](#testsauthenticate_as_service_role)\n  - [tests.clear_authentication()](#testsclear_authentication)\n  - [tests.rls_enabled(testing_schema text)](#testsrls_enabledtesting_schema-text)\n  - [tests.rls_enabled(testing_schema text, testing_table text)](#testsrls_enabledtesting_schema-text-testing_table-text)\n  - [tests.freeze_time(frozen_time timestamp with time zone)](#testsfreeze_timefrozen_time-timestamp-with-time-zone)\n  - [tests.unfreeze_time()](#testsunfreeze_time)\n- [Contributing](#contributing)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- include: supabase_test_helpers--0.0.4.sql --\u003e\n\n### tests.create_supabase_user(identifier text, email text, phone text)\n\nCreates a new user in the `auth.users` table.\nYou can recall a user's info by using `tests.get_supabase_user(identifier text)`.\n\nParameters:\n- `identifier` - A unique identifier for the user. We recommend you keep it memorable like \"test_owner\" or \"test_member\"\n- `email` - (Optional) The email address of the user\n- `phone` - (Optional) The phone number of the user\n- `metadata` - (Optional) Additional metadata to be added to the user\n\nReturns:\n- `user_id` - The UUID of the user in the `auth.users` table\n\nExample:\n```sql\n  SELECT tests.create_supabase_user('test_owner');\n  SELECT tests.create_supabase_user('test_member', 'member@test.com', '555-555-5555');\n  SELECT tests.create_supabase_user('test_member', 'member@test.com', '555-555-5555', '{\"key\": \"value\"}'::jsonb);\n```\n\n### tests.get_supabase_user(identifier text)\n\nReturns the user info for a user created with `tests.create_supabase_user`.\n\nParameters:\n- `identifier` - The unique identifier for the user\n\nReturns:\n- `user_id` - The UUID of the user in the `auth.users` table\n\nExample:\n```sql\n  SELECT posts where posts.user_id = tests.get_supabase_user('test_owner') -\u003e 'id';\n```\n\n### tests.get_supabase_uid(identifier text)\n\nReturns the user UUID for a user created with `tests.create_supabase_user`.\n\nParameters:\n- `identifier` - The unique identifier for the user\n\nReturns:\n- `user_id` - The UUID of the user in the `auth.users` table\n\nExample:\n```sql\n  SELECT posts where posts.user_id = tests.get_supabase_uid('test_owner') -\u003e 'id';\n```\n\n### tests.authenticate_as(identifier text)\n  Authenticates as a user created with `tests.create_supabase_user`.\n\nParameters:\n- `identifier` - The unique identifier for the user\n\nReturns:\n- `void`\n\nExample:\n```sql\n  SELECT tests.create_supabase_user('test_owner');\n  SELECT tests.authenticate_as('test_owner');\n```\n\n### tests.authenticate_as_service_role()\n  Clears authentication object and sets role to service_role.\n\nReturns:\n- `void`\n\nExample:\n```sql\n  SELECT tests.authenticate_as_service_role();\n```\n\n### tests.clear_authentication()\n  Clears out the authentication and sets role to anon\n\nReturns:\n- `void`\n\nExample:\n```sql\n  SELECT tests.create_supabase_user('test_owner');\n  SELECT tests.authenticate_as('test_owner');\n  SELECT tests.clear_authentication();\n```\n\n### tests.rls_enabled(testing_schema text)\npgTAP function to check if RLS is enabled on all tables in a provided schema\n\nParameters:\n- schema_name text - The name of the schema to check\n\nExample:\n```sql\n  BEGIN;\n      select plan(1);\n      select tests.rls_enabled('public');\n      SELECT * FROM finish();\n  ROLLBACK;\n```\n\n### tests.rls_enabled(testing_schema text, testing_table text)\npgTAP function to check if RLS is enabled on a specific table\n\nParameters:\n- schema_name text - The name of the schema to check\n- testing_table text - The name of the table to check\n\nExample:\n```sql\n   BEGIN;\n       select plan(1);\n       select tests.rls_enabled('public', 'accounts');\n       SELECT * FROM finish();\n   ROLLBACK;\n```\n\n### tests.freeze_time(frozen_time timestamp with time zone)\n\nOverwrites the current time from now() to the provided time.\n\nWorks out of the box for any normal usage of now(), if you have a function that sets its own search path, such as security definers, then you will need to alter the function to set the search path to include test_overrides BEFORE pg_catalog.\n**ONLY do this inside of a pgtap test transaction.**\nExample:\n\n```sql\nALTER FUNCTION auth.your_function() SET search_path = test_overrides, public, pg_temp, pg_catalog;\n```\nView a test example in 05-frozen-time.sql: https://github.com/usebasejump/supabase-test-helpers/blob/main/supabase/tests/05-frozen-time.sql\n\nParameters:\n- `frozen_time` - The time to freeze to. Supports timestamp with time zone, without time zone, date or any other value that can be coerced into a timestamp with time zone.\n\nReturns:\n- void\n\nExample:\n```sql\n  SELECT tests.freeze_time('2020-01-01 00:00:00');\n```\n\n### tests.unfreeze_time()\n\nUnfreezes the time and restores the original now() function.\n\nReturns:\n- void\n\nExample:\n```sql\n  SELECT tests.unfreeze_time();\n```\n\n\u003c!-- /include: supabase_test_helpers--0.0.4.sql --\u003e\n\n## Contributing\nYes, please! Anything you've found helpful for testing Supabase projects is welcome. To contribute:\n\n* Create a new version of supabase_test_helpers `supabase_test_helpers--{major}-{minor}-{patch}.sql`\n* New versions are intended to be a fresh install, so copy the contents of the previous version into the new version.\n* Add [pgTAP compliant test functions](https://pgtap.org/documentation.html#composeyourself) to the new version\n* Comments should be added above each function, follow the examples in the file.\n* Create a migration file `supabase_test_helpers--{oldMajor}-{oldMinor}-{oldPatch}--{newMajor}-{newMinor}-{newPatch}.sql` to upgrade to the new version. Include ONLY your migration code, not the entire contents of the new version.\n* Add tests for your functions in `supabase/tests/XX-your-function-name.sql`\n* You can verify tests work by running `supabase init` to create a config file, `supabase start` to launch it \n* Install your updated version with `dbdev install --connection postgres://postgres:postgres@localhost:54322/postgres --path .`\n* Run `supabase test db` to run the tests.\n* Submit a PR\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusebasejump%2Fsupabase-test-helpers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusebasejump%2Fsupabase-test-helpers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusebasejump%2Fsupabase-test-helpers/lists"}