Add documentation (#15)

* Add documentation

Closes #13

* Add documentation

Closes #13

README.md

@@ -6,3 +6,13 @@
 [![NPM](https://img.shields.io/npm/v/@kiwiproject/kiwi-test-js)](https://www.npmjs.com/package/@kiwiproject/kiwi-test-js)
 
 kiwi-test-js is a test utility library. Most of these utilities are ports from the Java Kiwi-test library (https://github.com/kiwiproject/kiwi-test).
+
+### TestContainers
+There are a few prebuilt implementations of starting up TestContainers to use in tests. These utilities allow for global
+setup and teardown methods to be created to run containers before all tests and after all tests not just per test file.
+Currently there are 4 implementations:
+
+* PostgresExtension - Spins up and shuts down a Postgres container for use and allows for creating databases
+* MongoExtension - Spins up and shuts down a Mongo container for use
+* ElasticSearchExtension - Spins up and shuts down a Elastic Search container for use
+* MinioExtension - Spins up and shuts down a Minio container for use

__tests__/minio/minio-extension.t.ts

@@ -11,10 +11,7 @@ describe("MinioExtension", () => {
 
   describe("startMinioContainer", () => {
     it("should start the minio container", async () => {
-      await MinioExtension.startMinioSearchContainer(
-        "minioadmin",
-        "keyboard cat",
-      );
+      await MinioExtension.startMinioContainer();
 
       expect(global.MINIO_CONTAINER).toBeDefined();
 
@@ -24,17 +21,14 @@ describe("MinioExtension", () => {
 
   describe("stopMinioContainer", () => {
     it("should stop the minio container", async () => {
-      await MinioExtension.startMinioSearchContainer(
-        "minioadmin",
-        "keyboard cat",
-      );
-      await MinioExtension.stopMinioSearchContainer();
+      await MinioExtension.startMinioContainer();
+      await MinioExtension.stopMinioContainer();
 
       expect(global.MINIO_CONTAINER).toBeUndefined();
     }, 60_000);
 
     it("should throw error when container is not previously started", () => {
-      expect(MinioExtension.stopMinioSearchContainer()).rejects.toEqual(
+      expect(MinioExtension.stopMinioContainer()).rejects.toEqual(
         Error(
           "IllegalStateException: Minio container has not been previously started",
         ),
@@ -46,10 +40,7 @@ describe("MinioExtension", () => {
 
   describe("getMinioPort", () => {
     it("should return the mapped port for the started container", async () => {
-      await MinioExtension.startMinioSearchContainer(
-        "minioadmin",
-        "keyboard cat",
-      );
+      await MinioExtension.startMinioContainer();
 
       const port = MinioExtension.getMinioPort();
       expect(port).toBeGreaterThan(0);

src/elasticsearch/elastic-search-extension.ts

@@ -1,6 +1,11 @@
 import { KiwiPreconditions } from "@kiwiproject/kiwi-js";
 import { ElasticsearchContainer } from "@testcontainers/elasticsearch";
 
+/**
+ * Starts an Elastic search container and stores the container information in global.ELASTIC_SEARCH_CONTAINER.
+ *
+ * @param image The image name/version to use for elastic search. Defaults to elasticsearch:8.6.1.
+ */
 async function startElasticSearchContainer(
   image: string = "elasticsearch:8.6.1",
 ) {
@@ -9,6 +14,10 @@ async function startElasticSearchContainer(
     .start();
 }
 
+/**
+ * Stops a previously started Elastic search container. Error will be thrown if startElasticSearchContainer was not
+ * previously called.
+ */
 async function stopElasticSearchContainer() {
   KiwiPreconditions.checkState(
     global.ELASTIC_SEARCH_CONTAINER !== undefined,
@@ -18,6 +27,10 @@ async function stopElasticSearchContainer() {
   global.ELASTIC_SEARCH_CONTAINER = undefined;
 }
 
+/**
+ * Retrieves the URL for accessing the running Elastic Search container. Error will be thrown if startElasticSearchContainer
+ * was not previously called.
+ */
 function getElasticSearchUrl(): string {
   KiwiPreconditions.checkState(
     global.ELASTIC_SEARCH_CONTAINER !== undefined,

src/minio/minio-extension.ts

@@ -1,9 +1,16 @@
 import { KiwiPreconditions } from "@kiwiproject/kiwi-js";
 import { GenericContainer, Wait } from "testcontainers";
 
-async function startMinioSearchContainer(
-  accessKey: string,
-  secretKey: string,
+/**
+ * Starts a Minio container and stores the container information in global.MINIO_CONTAINER
+ *
+ * @param accessKey The access key configured to connect. Defaults to minioadmin.
+ * @param secretKey The secret key configured to connect. Defaults to keyboard cat.
+ * @param image The image name/version to use for minio. Defaults to minio/minio:RELEASE.2023-08-09T23-30-22Z.
+ */
+async function startMinioContainer(
+  accessKey: string = "minioadmin",
+  secretKey: string = "keyboard cat",
   image: string = "minio/minio:RELEASE.2023-08-09T23-30-22Z",
 ) {
   global.MINIO_CONTAINER = await new GenericContainer(image)
@@ -21,7 +28,11 @@ async function startMinioSearchContainer(
     .start();
 }
 
-async function stopMinioSearchContainer() {
+/**
+ * Stops a previously started Minio container. Error will be thrown if startMinioContainer has not been
+ * previously called.
+ */
+async function stopMinioContainer() {
   KiwiPreconditions.checkState(
     global.MINIO_CONTAINER !== undefined,
     "Minio container has not been previously started",
@@ -30,6 +41,10 @@ async function stopMinioSearchContainer() {
   global.MINIO_CONTAINER = undefined;
 }
 
+/**
+ * Retrieves the mapped external port of the started Minio container. Error will be thrown if startMinioContainer was
+ * not previously called.
+ */
 function getMinioPort(): number {
   KiwiPreconditions.checkState(
     global.MINIO_CONTAINER !== undefined,
@@ -40,7 +55,7 @@ function getMinioPort(): number {
 }
 
 export const MinioExtension = {
-  startMinioSearchContainer,
-  stopMinioSearchContainer,
+  startMinioContainer,
+  stopMinioContainer,
   getMinioPort,
 };

src/mongo/mongo-extension.ts

@@ -1,12 +1,21 @@
 import { KiwiPreconditions } from "@kiwiproject/kiwi-js";
 import { GenericContainer } from "testcontainers";
 
+/**
+ * Starts a Mongo container and stores the container information in global.MONGO_CONTAINER.
+ *
+ * @param image The image name/version to use for mongo. Defaults to mongo:6.
+ */
 async function startMongoContainer(image: string = "mongo:6") {
   global.MONGO_CONTAINER = await new GenericContainer(image)
     .withExposedPorts(27017)
     .start();
 }
 
+/**
+ * Stops a previously started Mongo container. Error will be thrown if startMongoContainer is not
+ * previously called.
+ */
 async function stopMongoContainer() {
   KiwiPreconditions.checkState(
     global.MONGO_CONTAINER !== undefined,
@@ -16,6 +25,10 @@ async function stopMongoContainer() {
   global.MONGO_CONTAINER = undefined;
 }
 
+/**
+ * Retrieves the base connection URL for accessing the running Mongo. Error will be thrown if startMongoContainer
+ * is not previously called.
+ */
 function getMongoBaseUrl(): string {
   KiwiPreconditions.checkState(
     global.MONGO_CONTAINER !== undefined,
@@ -27,6 +40,11 @@ function getMongoBaseUrl(): string {
   return `mongodb://${host}:${port}/`;
 }
 
+/**
+ * Retrieves the base connection URL plus the given db name for accessing the running Mongo. Error will be thrown if
+ * startMongoContainer is not previously called.
+ * @param dbName The name of the database in mongo to connect.
+ */
 function getMongoUriWithDb(dbName: string): string {
   return `${getMongoBaseUrl()}${dbName}`;
 }

src/postgres/postgres-extension.ts

@@ -2,10 +2,19 @@ import { KiwiPreconditions } from "@kiwiproject/kiwi-js";
 import { PostgreSqlContainer } from "@testcontainers/postgresql";
 import { Client } from "pg";
 
+/**
+ * Starts a Postgres container and stores the container information in global.POSTGRES_CONTAINER.
+ *
+ * @param image The image name/version to use for postgres. Defaults to postgres:15.
+ */
 async function startPostgresContainer(image: string = "postgres:15") {
   global.POSTGRES_CONTAINER = await new PostgreSqlContainer(image).start();
 }
 
+/**
+ * Stops a previously started Postgres container. Error will be thrown if startPostgresContainer is not
+ * previously called.
+ */
 async function stopPostgresContainer() {
   KiwiPreconditions.checkState(
     global.POSTGRES_CONTAINER !== undefined,
@@ -15,6 +24,10 @@ async function stopPostgresContainer() {
   global.POSTGRES_CONTAINER = undefined;
 }
 
+/**
+ * Retrieves the base URL for accessing the running Postgres container. Error will be thrown if
+ * startPostgresContainer is not previously called.
+ */
 function getPostgresBaseUrl(): string {
   KiwiPreconditions.checkState(
     global.POSTGRES_CONTAINER !== undefined,
@@ -24,10 +37,22 @@ function getPostgresBaseUrl(): string {
   return global.POSTGRES_CONTAINER.getConnectionUri();
 }
 
+/**
+ * Retrieves the base URL plus a given database for accessing the running Postgres container. Error will be thrown if
+ * startPostgresContainer is not previously called.
+ *
+ * @param dbName The name of the database to add to the connection string.
+ */
 function getPostgresUriWithDb(dbName: string): string {
   return getPostgresBaseUrl().replace(/\/test$/, `/${dbName}`);
 }
 
+/**
+ * Creates a new database with the given name in the running Postgres. Error will be thrown if
+ * startPostgresContainer is not previously called.
+ *
+ * @param dbName The name of the database to create.
+ */
 async function setupNewDatabase(dbName: string) {
   const dbClient = new Client({
     connectionString: getPostgresBaseUrl(),