Testing

A test of code that uses Supabase needs no project and no network. Every call goes through the application's HttpTransport bean, and Realtime through its WebSocketTransport bean; a test replaces them with fakes, reads what was sent, and answers as the project would.

Why

A test against a real project is slow, needs keys in CI, and cannot easily answer with an error at the right moment. With a fake transport the application's code is as in production (the same repositories, the same credentials rule), and the test decides every answer.

One part by hand

MockHttpTransport comes with package:spring_boot_starter_test/spring_boot_starter_test.dart. This test builds a StorageTemplate over it:

import 'dart:typed_data';

import 'package:spring_boot_starter_supabase/spring_boot_starter_supabase.dart';
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:test/test.dart';

void main() {
  late MockHttpTransport transport;
  late StorageTemplate storage;

  setUp(() {
    transport = MockHttpTransport();
    final properties = SupabaseProperties()
      ..url = 'https://abcd.supabase.co'
      ..anonKey = 'anon-key';
    storage = StorageTemplate(
      http: SupabaseHttp(
        properties: properties,
        transport: transport,
        credentials: DefaultSupabaseCredentials(
          properties: properties,
          authentication: () => null,       // nobody is signed in
        ),
      ),
      mapper: ObjectMapper(),
    );
  });

  test('posts the bytes with the key, the token and the options', () async {
    transport
        .when(HttpMethod.post, '/storage/v1/object/avatars/u1/a b.png')
        .respond(200, json: {'Key': 'avatars/u1/a b.png'});

    await storage.upload(
      'avatars',
      'u1/a b.png',
      Uint8List.fromList([1, 2, 3]),
      contentType: 'image/png',
      upsert: true,
    );

    final request = transport.requests.single;
    expect(
      '${request.url}',
      'https://abcd.supabase.co/storage/v1/object/avatars/u1/a%20b.png',
    );
    expect(request.body, [1, 2, 3]);
    expect(request.headers['apikey'], 'anon-key');
    expect(request.headers['Authorization'], 'Bearer anon-key');
    expect(request.headers['x-upsert'], 'true');
    expect(request.followRedirects, isFalse);
  });

  test('a refused policy is a permission failure', () async {
    transport.when(HttpMethod.post, '/storage/v1/object/b/p').respond(
      400,
      json: {
        'statusCode': '403',
        'error': 'Unauthorized',
        'message': 'new row violates row-level security policy',
      },
    );
    await expectLater(
      storage.upload('b', 'p', const [1]),
      throwsA(isA<StoragePermissionDeniedException>()),
    );
  });
}

The whole application

ApplicationContextRunner starts the application with the starter's auto-configurations and the fake transport as its HttpTransport bean. The repositories and the declared interfaces are then the generated beans:

ApplicationContextRunner appRunner(MockHttpTransport transport) =>
    const ApplicationContextRunner()
        .withUserConfiguration($application)
        .withAutoConfiguration(springBootAutoConfiguration)
        .withAutoConfiguration(springSecurityCoreAutoConfiguration)
        .withAutoConfiguration(springBootStarterFeignAutoConfiguration)
        .withAutoConfiguration(springBootStarterWebsocketAutoConfiguration)
        .withAutoConfiguration(springBootStarterDataAutoConfiguration)
        .withAutoConfiguration(springBootStarterCacheAutoConfiguration)
        .withAutoConfiguration(springBootStarterSupabaseAutoConfiguration)
        .withPropertyValues([
          'spring.supabase.url=https://abcd.supabase.co',
          'spring.supabase.anon-key=anon-key',
        ])
        .withBean<HttpTransport>(() => transport);

test('a derived query becomes filters of the REST API', () async {
  final transport = MockHttpTransport();
  transport.when(HttpMethod.get, '/rest/v1/todos').respond(200, json: [
    {'id': 1, 'title': 'Buy milk', 'done': false},
  ]);

  await appRunner(transport).runAsync((context) async {
    expect(context.startupFailure, isNull);
    final found =
        await context.getBean<Todos>().findByDoneOrderByCreatedAtDesc(false);
    expect(found.single.title, 'Buy milk');
  });

  expect(
    Uri.decodeFull(transport.requests.single.url.query),
    'done=eq.false&order=created_at.desc',
  );
});

springBootStarterSupabaseAutoConfiguration and the others come from package:spring_boot_starter_supabase/spring_auto_configuration.dart.

Answers and failures

On the fake What the code sees
.respond(200, json: …) the answer
.respond(409, json: {'code': '23505', 'message': '…'}) a DuplicateKeyException from a repository
.respond(200, headers: {'Content-Range': '0-1/7'}) to the count (a GET with limit=0) the total of a Page
.fail(HttpTransportException('connection refused')) a DataAccessResourceFailureException from a repository, a SupabaseUnavailableException from Storage and Auth

A user

Realtime

MockWebSocketTransport plays the Realtime server: the test reads the frames the client sent and pushes the server's. The protocol is that of the Phoenix Channels client, in its first wire format (JSON objects with topic, event, payload, ref). The package's own tests build a SupabaseRealtime over a PhoenixSocketFactory with that transport.

The levels of the package's own tests

The starter's tests are tagged, by its dart_test.yaml:

Level Tag What Needs
1 supabase (every test file has it) Filters of the REST API, the Phoenix protocol against a fake server, Storage, Auth and functions against a fake HTTP transport, token checks with keys the tests make, path segments, cache keys with the caller nothing
2 and 3 supabase-docker The SQL path with spring.supabase.db.rls: user on a PostgreSQL container; the REST store against a real PostgREST over PostgreSQL with row-level security Docker. Skipped without it; a failure with CONTAINERS_REQUIRED=true
4 supabase-stack What only the real services answer The whole of Supabase (the Supabase CLI's stack, or a hosted project), given by SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY and SUPABASE_DB_URL. Skipped without them
dart test --exclude-tags "supabase-docker || supabase-stack"   # level 1
dart test --tags supabase-docker                               # levels 2 and 3
dart test --tags supabase-stack                                # level 4

The levels run in a pipeline of their own (.github/workflows/supabase.yml), not in the framework's main one: levels 1 to 3 in the jobs unit and containers, level 4 (test/stack_*_test.dart, with the Supabase CLI's configuration in test/stack/) in the job stack, against the Supabase CLI's local stack, and in hosted, against a hosted project when its address and keys are in the repository's secrets.

For containers that must reach each other (PostgreSQL and PostgREST), the test starter has networks. There is no Supabase container for an application's tests yet.

In Spring (Java)

MockHttpTransport plays the part of MockRestServiceServer, and ApplicationContextRunner is Spring Boot's.

See also