Testing Grouparoo

Testing your Grouparoo Application

In order to help fit Grouparoo into the CI/CD tools you use today, Grouparoo comes with testing utilities to which you can use to build a test suite that ensures that the application is producing the Records and Groups you expect. Grouparoo relies on Jest to provide expectations and snapshot testing. To enable Grouparoo testing:

1. npm install --save @grouparoo/spec-helper jest
2. create a .env.test file to store your test configuration.
3. Create a new test in a __tests__ directory within your project
4. Write your test
5. Run your test with ./node_modules/.bin/jest [path/to/test].
   • You can wire up npm test to run this for you.

When you test your Grouparoo application, you'll be testing your configuration files, Apps, Sources, and Destinations. Ideally, you have a specific Record in mind that you can fully sync. You can ensure that it ends up in the right Groups, and would be exported to the Destinations you expect.

.env.test

When running tests, you'll want to connect to a test-specific Grouparoo database. This is a great time to use sqlite and mock-redis so you don't need to provision a "real" database for your tests. You can also safely disable the webserver and workers.

An example .env.test could be:

#############
## GENERAL ##
#############

WEB_SERVER=false
WORKERS=0
SERVER_TOKEN=test-server-token
GROUPAROO_TELEMETRY_ENABLED=false

#############
## LOGGING ##
#############

GROUPAROO_LOG_LEVEL=info

###########
## REDIS ##
###########

REDIS_URL="redis://mock"

##############
## DATABASE ##
##############

DATABASE_URL="sqlite://grouparoo_test.sqlite"

In your test file, you'll be setting process.env.DATABASE_URL = "sqlite://test_db.sqlite"; so the test will know which environment file to use.

Writing Tests

In Jest, you can do expectation testing (a should equal 1) or snapshot testing (the output of this method should not change between tests). Grouparoo supports both! The following example demonstrates a full suite which does both expectation testing and snapshot testing.

In this example:

• Your application is already fully configured with Apps, Sources, etc via Config UI.
• You have specified a test postgres or SQLite database to use via DATABASE_URL or a test-specific GROUPAROO_ENV_CONFIG_FILE
• "person@example" is a user in your source database that we are testing.

/**
 * @jest-environment node
 */

// Where should we load the test environment from?
// You'll probably want a similar config to your normal .env file, but with a different database and 0 workers
// Set before requiring @grouparoo/spec-helper
process.env.GROUPAROO_ENV_CONFIG_FILE = `.env.test`;

const { helper, relaxedSnapshot } = require("@grouparoo/spec-helper");

describe("snapshot", () => {
  // utility to start and stop the server within the test suite
  helper.grouparooTestServer();

  test("a record snapshot can be tested", async () => {
    const { record, snapshot } = await helper.getRecord({
      email: "person@example",
    });

    // You can do snapshot testing
    // `relaxedSnapshot` lets you skip time and UUID generated properties, but ensure everything else matches exactly
    expect(snapshot).toMatchSnapshot(relaxedSnapshot(snapshot));

    // Or you can test the properties of the snapshot directly
    expect(snapshot.properties.userId.values).toEqual([100]);
    expect(snapshot.groups.length).toBe(1);
    expect(snapshot.groups[0].name).toBe("People with Email Addresses");
    expect(record.state).toBe("ready");
  });
});

Testing Notes

• Unless you specify in your package.json or jest.config.js, You'll need to use magic comments to let Jest know that we are running a Node.js App (@jest-environment node)

Spec Helper API

The spec helper makes a few helpful methods available to you. Here are the commonly-used methods and options:

grouparooTestServer

Starts a test version of the Grouparoo server prior to running the specs and stops it after running the tests.

Usage:

helper.grouparooTestServer();

Options may be passed to grouparooTestServer as an object. The main option of use to you is truncate, which tells the helper to truncate the database prior to running the specs.

helper.grouparooTestServer({ truncate: false });

getRecord

Retrieves a Record from a series of key-value pairs representing properties of that Record.

Usage:

const record = await helper.getRecord({
  user_id: 100,
  email: "example@example.com",
});