​
What to test

It is valuable to test the Sequin configurations that developers are responsible for writing and maintaining, especially source configuration, filters, transforms, and routing.

It is also valuable to test end-to-end connectivity between your source databases and sink destinations, often in a cloud CI environment.

​
Prerequisites

Before testing, you should familiarize yourself with Sequin and implement the sinks that you want to test. You’ll also need a test or CI environment for your application infrastructure.

  • A sequin.yaml file for your sinks that you want to test. This is used to programmatically configure Sequin in test environments
  • Tooling to run Sequin in your test environment (e.g. Docker, Helm, etc.)
  • A test / CI database with logical replication enabled

​
Local testing

The primary benefit of testing Sequin locally is to proactively catch when schema migrations will break your sink configuration. This is especially useful when you have many tables in a sink or have relatively complex filters, transforms, and routing.

If your sink configuration only includes a single table and transforms that simply removes metadata, it’s often sufficient to stub out the payload you expect from Sequin.

1

Configure your test database

Ensure that your test database is properly configured for logical replication. As a best practice, you should create a dedicated sequin_test user with replication privileges.

2

Re-use your `sequin.yml` for testing

Use environment variables to repurpose your development sequin.yml as your test configuration. This ensures that your current dev configuration is properly tested without needing to update a separate sequin.yml file.

For instance, you can use environment variables in yoursequin.yml to create:

Use YAML anchors to easily reuse elements of your sink configurations.

Use the sequin config interpolate command to preview your sequin.yml file after environment variables are interpolated. This will help you catch any issues with your environment variables.

3

Create a test-specific Sequin environment

Create a new docker-compose.test.yml (or helm, etc.) file that includes all the necessary services to run Sequin in a test environment. This should include the Sequin service and it’s dependent Postgres and Redis services. A couple considerations:

  1. Ensure that the Sequin service boots up using your test environment variables and the sequin.yml configuration file:

    sequin:
  # ...
  CONFIG_FILE_PATH: sequin.test.yml

  2. For testing, you don’t need to spin up Prometheus and Grafana.

  3. You can safely disable telemetry by setting the TELEMETRY_ENABLED environment variable to false.

4

Write and run your tests

Write tests to verify that your sink configuration is working as expected. This includes:

  • Verifying that the correct data is being delivered to the destination. Assert that the payload matches your expectations.
  • Verifying that filters are excluding and including the correct changes.
  • Verifying that dynamic routers are working as you’d expect.
  • Verifying that your transforms are working as you’d expect.

Be sure that transactions are fully committed to your test database if you expect them to be replicated through Sequin.

Some ORMs use transaction isolation to allow concurrent testing which must be disabled to allow messages to replicate to Sequin. This, however, requires that tests are run sequentially instead of in parallel.

For sink destinations that are hard to set up in a test environment, you can use a Sequin stream as a mock destination. This allows you to verify the data transformation, filtering, and payload delivered to the destination without needing the actual destination system. Be sure to acknowledge the messages in the stream to avoid duplicate delivery, and run your tests sequentially to avoid race conditions.

​
CI Integration

Local unit testing will ensure that any changes you make to your database schema, sink configuration, or other Sequin components deliver the correct data to your destination.

In CI, you should test that Sequin can properly integrate with your infrastructure and deliver the correct data to your destination.

1

Create CI sequin.yml

For CI, you’ll often use the same sequin.yml file as you’ll run in production - but use environment variables to properly configure your database connections and sinks for your CI environment.

A couple considerations in CI:

  • For your database configuration, its appropriate to have Sequin create both the replication slot and publication.
  • Ensure your sinks use similar filters, transforms, and routing as you’ll use in production to properly test your sink configuration.

Use YAML anchors to easily reuse elements of your sink configurations.

Use the sequin config interpolate command to preview your sequin.yml file after environment variables are interpolated. This will help you catch any issues with your environment variables.

2

Provision Sequin in your CI environment

Provision Sequin and it’s dependent services in your CI environment - you can use Docker or whatever tooling you’re using to run Sequin. A couple considerations:

  1. Ensure that the Sequin service boots up using your CI environment variables and the sequin.ci.yml configuration file:

    sequin:
  # ...
  CONFIG_FILE_PATH: sequin.ci.yml

  2. For testing, you don’t need to spin up Prometheus and Grafana.

  3. You can safely disable telemetry by setting the TELEMETRY_ENABLED environment variable to false.

3

Run a script and leverage the Sequin API to run integration tests

Write a script to ensure Sequin spins up properly, connects to your database, and delivers the correct data to your sinks:

  • Check that Sequin’s /health endpoint is returning a 200 status code.
  • Commit transactions to your database and validate that the data is being delivered to your sinks.
  • Use the Sequin API to check the health of your sinks and test backfills as well.
  • Verify that any filtering, transforms, and routing are working as expected and that the payload delivered to your sinks matches your assertions.

You should test Sequin synchronously. This ensures that your tests are not affected by race conditions.

Be sure that transactions are fully committed to your test database if you expect them to be reflected in your Sequin tests. Often ORMs will automatically rollback transactions.

​
Next Steps

With testing in place, you can be confident changes to your application, schema, and sink configurations behave as you expect. From here, focus on shipping to production:

Deploy Sequin in production

Learn how to deploy Sequin in production.

Learn more about sequin.yml

Learn how to work configure Sequin using sequin.yml.

Learn more about Sequin's API

Learn how to use Sequin’s API to test your sink configuration.

Monitor your workflows

Learn how to monitor your system with Sequin’s built-in metrics.