
# 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:

```dart
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`](../spring-boot-starter-test/application-context-runner.md) 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:

```dart
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

- **Nobody:** the anon key, as above.
- **A signed-in user of a client application:** give `DefaultSupabaseCredentials` a `session:` that returns a `LoginSession` of the test, or answer `/auth/v1/token?grant_type=password` on the fake and call `SupabaseAuth.signInWithPassword`.
- **The service role:** set `spring.supabase.service-role-key` and call inside `asServiceRole`; the request then has that key as `apikey` and as the bearer token.
- **A user for `@PreAuthorize`** only: `SecurityContextHolder.runWithContext` with a `TestingAuthenticationToken`, as in any test of [method security](../spring-security-core/testing.md). Such a user has no token of Supabase, so the calls go out with the anon key.

## 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](../spring-boot-starter-websocket/phoenix.md), 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 |

```bash
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](../spring-boot-starter-test/containers.md). 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

- [ApplicationContextRunner](../spring-boot-starter-test/application-context-runner.md)
- [Testing HTTP clients](../spring-web-dart/testing.md)
- [Containers](../spring-boot-starter-test/containers.md)
- [Who a call is made as](credentials.md)
