rename to backend-test-utils and rearrange a bit

Signed-off-by: Fredrik Adelöw <freben@gmail.com>

packages/backend-test-utils/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: [require.resolve('@backstage/cli/config/eslint.backend')],
+};

packages/backend-test-utils/README.md

@@ -0,0 +1,18 @@
+# @backstage/backend-test-utils
+
+Test helpers library for Backstage backends.
+
+## Usage
+
+Add the library as a `devDependency` to your backend package:
+
+```sh
+# From the Backstage root directory, go to your backend package, or to a backend plugin
+cd plugins/my-plugin-backend
+yarn add --dev @backstage/backend-test-utils
+```
+
+## Documentation
+
+- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
+- [Backstage Documentation](https://github.com/backstage/backstage/blob/master/docs/README.md)

packages/backend-test-utils/api-report.md

@@ -0,0 +1,31 @@
+## API Report File for "@backstage/backend-test-utils"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { Knex } from 'knex';
+
+// @public (undocumented)
+export function isDockerDisabledForTests(): boolean;
+
+// @public
+export type TestDatabaseId = 'POSTGRES_13' | 'POSTGRES_9' | 'MYSQL_8' | 'SQLITE_3';
+
+// @public
+export class TestDatabases {
+    static create(options?: {
+        ids?: TestDatabaseId[];
+        disableDocker?: boolean;
+    }): TestDatabases;
+    // (undocumented)
+    eachSupportedId(): [TestDatabaseId][];
+    init(id: TestDatabaseId): Promise<Knex>;
+    // (undocumented)
+    supports(id: TestDatabaseId): boolean;
+}
+
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/backend-test-utils/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@backstage/backend-test-utils",
+  "description": "Test helpers library for Backstage backends",
+  "version": "0.1.1",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/backend-test-utils"
+  },
+  "keywords": [
+    "backstage",
+    "test"
+  ],
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "backstage-cli build --outputs cjs,types",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "prepack": "backstage-cli prepack",
+    "postpack": "backstage-cli postpack",
+    "clean": "backstage-cli clean"
+  },
+  "dependencies": {
+    "@backstage/backend-common": "^0.8.0",
+    "@backstage/cli": "^0.6.10",
+    "@backstage/config": "^0.1.5",
+    "knex": "^0.95.1",
+    "mysql2": "^2.2.5",
+    "pg": "^8.3.0",
+    "sqlite3": "^5.0.0",
+    "testcontainers": "^7.10.0",
+    "uuid": "^8.0.0"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.6.10",
+    "jest": "^26.0.1"
+  },
+  "files": [
+    "dist"
+  ]
+}

packages/backend-test-utils/src/database/TestDatabases.test.ts

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import knexFactory from 'knex';
+import { isDockerDisabledForTests } from '../util/isDockerDisabledForTests';
+import { startMysqlContainer } from './startMysqlContainer';
+import { startPostgresContainer } from './startPostgresContainer';
+import { TestDatabases } from './TestDatabases';
+
+const itIfDocker = isDockerDisabledForTests() ? it.skip : it;
+
+describe('TestDatabases', () => {
+  const OLD_ENV = process.env;
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...OLD_ENV };
+  });
+  afterAll(() => {
+    process.env = OLD_ENV;
+  });
+
+  describe('each', () => {
+    const dbs = TestDatabases.create();
+
+    it.each(dbs.eachSupportedId())(
+      'creates distinct %p databases',
+      async databaseId => {
+        if (!dbs.supports(databaseId)) {
+          return;
+        }
+        const db1 = await dbs.init(databaseId);
+        const db2 = await dbs.init(databaseId);
+        await db1.schema.createTable('a', table => table.string('x').primary());
+        await db2.schema.createTable('a', table => table.string('y').primary());
+        await expect(db1.select({ a: db1.raw('1') })).resolves.toEqual([
+          { a: 1 },
+        ]);
+      },
+      60_000,
+    );
+  });
+
+  itIfDocker(
+    'obeys a provided connection string for postgres 13',
+    async () => {
+      const dbs = TestDatabases.create();
+      const { host, port, user, password, stop } = await startPostgresContainer(
+        'postgres:13',
+      );
+
+      try {
+        // Leave a mark
+        process.env.BACKSTAGE_TEST_DATABASE_POSTGRES13_CONNECTION_STRING = `postgresql://${user}:${password}@${host}:${port}`;
+        const input = await dbs.init('POSTGRES_13');
+        await input.schema.createTable('a', table =>
+          table.string('x').primary(),
+        );
+        await input.insert({ x: 'y' }).into('a');
+
+        // Look for the mark
+        const database = 'backstage_plugin_0';
+        const output = knexFactory({
+          client: 'pg',
+          connection: { host, port, user, password, database },
+        });
+        // eslint-disable-next-line jest/no-standalone-expect
+        await expect(output.select('x').from('a')).resolves.toEqual([
+          { x: 'y' },
+        ]);
+      } finally {
+        await stop();
+      }
+    },
+    60_000,
+  );
+
+  itIfDocker(
+    'obeys a provided connection string for postgres 9',
+    async () => {
+      const dbs = TestDatabases.create();
+      const { host, port, user, password, stop } = await startPostgresContainer(
+        'postgres:9',
+      );
+
+      try {
+        // Leave a mark
+        process.env.BACKSTAGE_TEST_DATABASE_POSTGRES9_CONNECTION_STRING = `postgresql://${user}:${password}@${host}:${port}`;
+        const input = await dbs.init('POSTGRES_9');
+        await input.schema.createTable('a', table =>
+          table.string('x').primary(),
+        );
+        await input.insert({ x: 'y' }).into('a');
+
+        // Look for the mark
+        const database = 'backstage_plugin_0';
+        const output = knexFactory({
+          client: 'pg',
+          connection: { host, port, user, password, database },
+        });
+        // eslint-disable-next-line jest/no-standalone-expect
+        await expect(output.select('x').from('a')).resolves.toEqual([
+          { x: 'y' },
+        ]);
+      } finally {
+        await stop();
+      }
+    },
+    60_000,
+  );
+
+  itIfDocker(
+    'obeys a provided connection string for mysql 8',
+    async () => {
+      const dbs = TestDatabases.create();
+      const { host, port, user, password, stop } = await startMysqlContainer(
+        'mysql:8',
+      );
+
+      try {
+        // Leave a mark
+        process.env.BACKSTAGE_TEST_DATABASE_MYSQL8_CONNECTION_STRING = `mysql://${user}:${password}@${host}:${port}/ignored`;
+        const input = await dbs.init('MYSQL_8');
+        await input.schema.createTable('a', table =>
+          table.string('x').primary(),
+        );
+        await input.insert({ x: 'y' }).into('a');
+
+        // Look for the mark
+        const database = 'backstage_plugin_0';
+        const output = knexFactory({
+          client: 'mysql2',
+          connection: { host, port, user, password, database },
+        });
+        // eslint-disable-next-line jest/no-standalone-expect
+        await expect(output.select('x').from('a')).resolves.toEqual([
+          { x: 'y' },
+        ]);
+      } finally {
+        await stop();
+      }
+    },
+    60_000,
+  );
+});

packages/backend-test-utils/src/database/TestDatabases.ts

@@ -0,0 +1,274 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { SingleConnectionDatabaseManager } from '@backstage/backend-common';
+import { ConfigReader } from '@backstage/config';
+import { Knex } from 'knex';
+import { isDockerDisabledForTests } from '../util/isDockerDisabledForTests';
+import { startMysqlContainer } from './startMysqlContainer';
+import { startPostgresContainer } from './startPostgresContainer';
+import {
+  allDatabases,
+  Instance,
+  TestDatabaseId,
+  TestDatabaseProperties,
+} from './types';
+
+/**
+ * Encapsulates the creation of ephemeral test database instances for use
+ * inside unit or integration tests.
+ */
+export class TestDatabases {
+  private readonly instanceById: Map<string, Instance>;
+  private readonly supportedIds: TestDatabaseId[];
+  private lastDatabaseIndex: number;
+
+  /**
+   * Creates an empty `TestDatabases` instance, and sets up Jest to clean up
+   * all of its acquired resources after all tests finish.
+   *
+   * You typically want to create just a single instance like this at the top
+   * of your test file or `describe` block, and then call `init` many times on
+   * that instance inside the individual tests. Spinning up a "physical"
+   * database instance takes a considerable amount of time, slowing down tests.
+   * But initializing a new logical database inside that instance using `init`
+   * is very fast.
+   */
+  static create(options?: {
+    ids?: TestDatabaseId[];
+    disableDocker?: boolean;
+  }): TestDatabases {
+    const defaultOptions = {
+      ids: Object.keys(allDatabases) as TestDatabaseId[],
+      disableDocker: isDockerDisabledForTests(),
+    };
+
+    const { ids, disableDocker } = Object.assign(defaultOptions, options ?? {});
+
+    const supportedIds = ids.filter(id => {
+      const properties = allDatabases[id];
+      if (!properties) {
+        return false;
+      }
+      // If the caller has set up the env with an explicit connection string,
+      // we'll assume that this database will work
+      if (
+        properties.connectionStringEnvironmentVariableName &&
+        process.env[properties.connectionStringEnvironmentVariableName]
+      ) {
+        return true;
+      }
+      // If the database doesn't require docker at all, there's nothing to worry
+      // about
+      if (!properties.dockerImageName) {
+        return true;
+      }
+      // If the database requires docker, but docker is disabled, we will fail.
+      if (disableDocker) {
+        return false;
+      }
+      return true;
+    });
+
+    const databases = new TestDatabases(supportedIds);
+
+    afterAll(async () => {
+      await databases.shutdown();
+    });
+
+    return databases;
+  }
+
+  private constructor(supportedIds: TestDatabaseId[]) {
+    this.instanceById = new Map();
+    this.supportedIds = supportedIds;
+    this.lastDatabaseIndex = 0;
+  }
+
+  supports(id: TestDatabaseId): boolean {
+    return this.supportedIds.includes(id);
+  }
+
+  eachSupportedId(): [TestDatabaseId][] {
+    return this.supportedIds.map(id => [id]);
+  }
+
+  /**
+   * Returns a fresh, unique, empty logical database on an instance of the
+   * given database ID platform.
+   *
+   * @param id The ID of the database platform to use, e.g. 'POSTGRES_13'
+   * @returns A `Knex` connection object
+   */
+  async init(id: TestDatabaseId): Promise<Knex> {
+    const properties = allDatabases[id];
+    if (!properties) {
+      const candidates = Object.keys(allDatabases).join(', ');
+      throw new Error(
+        `Unknown test database ${id}, possible values are ${candidates}`,
+      );
+    }
+    if (!this.supportedIds.includes(id)) {
+      const candidates = this.supportedIds.join(', ');
+      throw new Error(
+        `Unsupported test database ${id} for this environment, possible values are ${candidates}`,
+      );
+    }
+
+    let instance: Instance | undefined = this.instanceById.get(id);
+
+    // Ensure that a testcontainers instance is up for this ID
+    if (!instance) {
+      instance = await this.initAny(properties);
+      this.instanceById.set(id, instance);
+    }
+
+    // Ensure that a unique logical database is created in the instance
+    const connection = await instance.databaseManager
+      .forPlugin(String(this.lastDatabaseIndex++))
+      .getClient();
+
+    instance.connections.push(connection);
+
+    return connection;
+  }
+
+  private async initAny(properties: TestDatabaseProperties): Promise<Instance> {
+    // Use the connection string if provided
+    if (properties.driver === 'pg' || properties.driver === 'mysql2') {
+      const envVarName = properties.connectionStringEnvironmentVariableName;
+      if (envVarName) {
+        const connectionString = process.env[envVarName];
+        if (connectionString) {
+          const databaseManager = SingleConnectionDatabaseManager.fromConfig(
+            new ConfigReader({
+              backend: {
+                database: {
+                  client: properties.driver,
+                  connection: connectionString,
+                },
+              },
+            }),
+          );
+          return {
+            databaseManager,
+            connections: [],
+          };
+        }
+      }
+    }
+
+    // Otherwise start a container for the purpose
+    switch (properties.driver) {
+      case 'pg':
+        return this.initPostgres(properties);
+      case 'mysql2':
+        return this.initMysql(properties);
+      case 'sqlite3':
+        return this.initSqlite(properties);
+      default:
+        throw new Error(`Unknown database driver ${properties.driver}`);
+    }
+  }
+
+  private async initPostgres(
+    properties: TestDatabaseProperties,
+  ): Promise<Instance> {
+    const { host, port, user, password, stop } = await startPostgresContainer(
+      properties.dockerImageName!,
+    );
+
+    const databaseManager = SingleConnectionDatabaseManager.fromConfig(
+      new ConfigReader({
+        backend: {
+          database: {
+            client: 'pg',
+            connection: { host, port, user, password },
+          },
+        },
+      }),
+    );
+
+    return {
+      stopContainer: stop,
+      databaseManager,
+      connections: [],
+    };
+  }
+
+  private async initMysql(
+    properties: TestDatabaseProperties,
+  ): Promise<Instance> {
+    const { host, port, user, password, stop } = await startMysqlContainer(
+      properties.dockerImageName!,
+    );
+
+    const databaseManager = SingleConnectionDatabaseManager.fromConfig(
+      new ConfigReader({
+        backend: {
+          database: {
+            client: 'mysql2',
+            connection: { host, port, user, password },
+          },
+        },
+      }),
+    );
+
+    return {
+      stopContainer: stop,
+      databaseManager,
+      connections: [],
+    };
+  }
+
+  private async initSqlite(
+    _properties: TestDatabaseProperties,
+  ): Promise<Instance> {
+    const databaseManager = SingleConnectionDatabaseManager.fromConfig(
+      new ConfigReader({
+        backend: {
+          database: {
+            client: 'sqlite3',
+            connection: ':memory:',
+          },
+        },
+      }),
+    );
+
+    return {
+      databaseManager,
+      connections: [],
+    };
+  }
+
+  private async shutdown() {
+    const instances = [...this.instanceById.values()];
+    await Promise.all(
+      instances.map(async ({ stopContainer, connections }) => {
+        try {
+          await Promise.all(connections.map(c => c.destroy()));
+        } catch {
+          // ignore
+        }
+        try {
+          await stopContainer?.();
+        } catch {
+          // ignore
+        }
+      }),
+    );
+  }
+}

packages/backend-test-utils/src/database/index.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { isDockerDisabledForTests } from '../util/isDockerDisabledForTests';
+export { TestDatabases } from './TestDatabases';
+export type { TestDatabaseId } from './types';

packages/backend-test-utils/src/database/startMysqlContainer.test.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import createConnection from 'knex';
+import { isDockerDisabledForTests } from '../util/isDockerDisabledForTests';
+import { startMysqlContainer } from './startMysqlContainer';
+
+const itIfDocker = isDockerDisabledForTests() ? it.skip : it;
+
+describe('startMysqlContainer', () => {
+  itIfDocker(
+    'successfully launches the container',
+    async () => {
+      const { stop, ...connection } = await startMysqlContainer('mysql:8');
+      const db = createConnection({ client: 'mysql2', connection });
+      try {
+        const result = await db.select(db.raw('version() AS version'));
+        // eslint-disable-next-line jest/no-standalone-expect
+        expect(result[0]?.version).toContain('8.');
+      } finally {
+        await db.destroy();
+        await stop();
+      }
+    },
+    60_000,
+  );
+});

packages/backend-test-utils/src/database/startMysqlContainer.ts

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import createConnection, { Knex } from 'knex';
+import { GenericContainer } from 'testcontainers';
+import { v4 as uuid } from 'uuid';
+
+async function waitForMysqlReady(
+  connection: Knex.MySqlConnectionConfig,
+): Promise<void> {
+  const startTime = Date.now();
+  const db = createConnection({ client: 'mysql2', connection });
+
+  try {
+    for (;;) {
+      try {
+        const result = await db.select(db.raw('version() AS version'));
+        if (result[0]?.version) {
+          return;
+        }
+      } catch (e) {
+        if (Date.now() - startTime > 30_000) {
+          throw new Error(
+            `Timed out waiting for the database to be ready for connections, ${e}`,
+          );
+        }
+      }
+
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  } finally {
+    db.destroy();
+  }
+}
+
+export async function startMysqlContainer(image: string) {
+  const user = 'root';
+  const password = uuid();
+
+  const container = await new GenericContainer(image)
+    .withExposedPorts(3306)
+    .withEnv('MYSQL_ROOT_PASSWORD', password)
+    .withTmpFs({ '/var/lib/mysql': 'rw' })
+    .start();
+
+  const host = container.getHost();
+  const port = container.getMappedPort(3306);
+  const stop = async () => {
+    await container.stop({ timeout: 10_000 });
+  };
+
+  await waitForMysqlReady({ host, port, user, password });
+
+  return { host, port, user, password, stop };
+}

packages/backend-test-utils/src/database/startPostgresContainer.test.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import createConnection from 'knex';
+import { isDockerDisabledForTests } from '../util/isDockerDisabledForTests';
+import { startPostgresContainer } from './startPostgresContainer';
+
+const itIfDocker = isDockerDisabledForTests() ? it.skip : it;
+
+describe('startPostgresContainer', () => {
+  itIfDocker(
+    'successfully launches the container',
+    async () => {
+      const { stop, ...connection } = await startPostgresContainer(
+        'postgres:13',
+      );
+      const db = createConnection({ client: 'pg', connection });
+      try {
+        const result = await db.select(db.raw('version()'));
+        // eslint-disable-next-line jest/no-standalone-expect
+        expect(result[0]?.version).toContain('PostgreSQL');
+      } finally {
+        await db.destroy();
+        await stop();
+      }
+    },
+    60_000,
+  );
+});

packages/backend-test-utils/src/database/startPostgresContainer.ts

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import createConnection, { Knex } from 'knex';
+import { GenericContainer } from 'testcontainers';
+import { v4 as uuid } from 'uuid';
+
+async function waitForPostgresReady(
+  connection: Knex.PgConnectionConfig,
+): Promise<void> {
+  const startTime = Date.now();
+  const db = createConnection({ client: 'pg', connection });
+
+  try {
+    for (;;) {
+      try {
+        const result = await db.select(db.raw('version()'));
+        if (Array.isArray(result) && result[0]?.version) {
+          return;
+        }
+      } catch (e) {
+        if (Date.now() - startTime > 30_000) {
+          throw new Error(
+            `Timed out waiting for the database to be ready for connections, ${e}`,
+          );
+        }
+      }
+
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+  } finally {
+    db.destroy();
+  }
+}
+
+export async function startPostgresContainer(image: string) {
+  const user = 'postgres';
+  const password = uuid();
+
+  const container = await new GenericContainer(image)
+    .withExposedPorts(5432)
+    .withEnv('POSTGRES_PASSWORD', password)
+    .withTmpFs({ '/var/lib/postgresql/data': 'rw' })
+    .start();
+
+  const host = container.getHost();
+  const port = container.getMappedPort(5432);
+  const stop = async () => {
+    await container.stop({ timeout: 10_000 });
+  };
+
+  await waitForPostgresReady({ host, port, user, password });
+
+  return { host, port, user, password, stop };
+}

packages/backend-test-utils/src/database/types.ts

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { SingleConnectionDatabaseManager } from '@backstage/backend-common';
+import { Knex } from 'knex';
+
+/**
+ * The possible databases to test against.
+ */
+export type TestDatabaseId =
+  | 'POSTGRES_13'
+  | 'POSTGRES_9'
+  | 'MYSQL_8'
+  | 'SQLITE_3';
+
+export type TestDatabaseProperties = {
+  name: string;
+  driver: string;
+  dockerImageName?: string;
+  connectionStringEnvironmentVariableName?: string;
+};
+
+export type Instance = {
+  stopContainer?: () => Promise<void>;
+  databaseManager: SingleConnectionDatabaseManager;
+  connections: Array<Knex>;
+};
+
+export const allDatabases: Record<
+  TestDatabaseId,
+  TestDatabaseProperties
+> = Object.freeze({
+  POSTGRES_13: {
+    name: 'Postgres 13.x',
+    driver: 'pg',
+    dockerImageName: 'postgres:13',
+    connectionStringEnvironmentVariableName:
+      'BACKSTAGE_TEST_DATABASE_POSTGRES13_CONNECTION_STRING',
+  },
+  POSTGRES_9: {
+    name: 'Postgres 9.x',
+    driver: 'pg',
+    dockerImageName: 'postgres:9',
+    connectionStringEnvironmentVariableName:
+      'BACKSTAGE_TEST_DATABASE_POSTGRES9_CONNECTION_STRING',
+  },
+  MYSQL_8: {
+    name: 'MySQL 8.x',
+    driver: 'mysql2',
+    dockerImageName: 'mysql:8',
+    connectionStringEnvironmentVariableName:
+      'BACKSTAGE_TEST_DATABASE_MYSQL8_CONNECTION_STRING',
+  },
+  SQLITE_3: {
+    name: 'SQLite 3.x',
+    driver: 'sqlite3',
+  },
+});

packages/backend-test-utils/src/index.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './database';
+export * from './util';

packages/backend-test-utils/src/setupTests.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {};

packages/backend-test-utils/src/util/index.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { isDockerDisabledForTests } from './isDockerDisabledForTests';

packages/backend-test-utils/src/util/isDockerDisabledForTests.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2021 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export function isDockerDisabledForTests() {
+  return Boolean(process.env.BACKSTAGE_TEST_DISABLE_DOCKER);
+}