open-index/open-npm huggingface dataset:
npm package: @stacks/api-test-toolkit
Description: Test utilities for @stacks/api-toolkit
Author: Stacks Labs
Latest version: 1.13.0

# @stacks/api-test-toolkit

Test utilities for integration tests that need Docker-managed dependencies (for example Postgres).

## Installation

```bash
npm install -D @stacks/api-test-toolkit
```

This package expects Docker to be available on the machine running tests.

## Quick Start

Use the toolkit in your test global setup/teardown hooks.

```ts
import type { DockerTestContainerConfig } from '@stacks/api-test-toolkit';
import { dockerTestDown, dockerTestUp } from '@stacks/api-test-toolkit';

const postgres: DockerTestContainerConfig = {
  image: 'postgres:17',
  name: 'my-api-test-postgres',
  ports: [{ host: 5432, container: 5432 }],
  env: ['POSTGRES_USER=postgres', 'POSTGRES_PASSWORD=postgres', 'POSTGRES_DB=postgres'],
};

export async function globalSetup() {
  await dockerTestUp({ config: postgres });
}

export async function globalTeardown() {
  await dockerTestDown({ config: postgres });
}
```

## API

### `dockerTestUp({ config })`

Creates (or starts) the container and waits until it is reachable on TCP by default.

- Pulls image if missing
- Reuses an existing container with the same name
- Waits for readiness unless `waitForReady` is set to `false`

### `dockerTestDown({ config })`

Stops and removes the container if it exists.

- No-op if the container is already absent

### `dockerTestLogs({ config, argv })`

Streams or prints recent container logs.

- Follows logs by default
- Use `argv: ['--once']` to print once and exit
- `-f` / `--follow` force streaming mode

## `DockerTestContainerConfig`

Required fields:

- `image`: Docker image name (example: `postgres:17`)
- `name`: Docker container name
- `ports`: host/container port mapping array

Common optional fields:

- `host`: bind address (default: `127.0.0.1`)
- `waitPort`: host-side port to probe for readiness
- `waitForReady`: disable readiness check when set to `false`
- `env`: environment variables (`KEY=value`)
- `entrypoint`, `command`
- `volumes`: mount strings in `host:container` format
- `extraHosts`: `hostname:ip` entries
- `healthcheck`: shell command passed as Docker `CMD-SHELL`
- `restartPolicy`: `no | always | on-failure | unless-stopped`
- `labels`
- `timeoutMs`: readiness timeout (default: `120000`)

## Docker client environment

By default, Docker is accessed through:

- `DOCKER_SOCKET_PATH` (defaults to `/var/run/docker.sock`)

If `DOCKER_HOST` is set, it is used instead.

## Notes

- Prefer `import type` for TypeScript-only symbols:
  - `import type { DockerTestContainerConfig } from '@stacks/api-test-toolkit'`
- Container names should be unique per test suite to avoid clashes.

## License

Apache 2.0
npm package: @stacks/api-toolkit
Description: API development toolkit
Author: Stacks Labs
Latest version: 1.13.0


# @stacks/api-toolkit

[![NPM Package](https://img.shields.io/npm/v/@stacks/api-toolkit.svg?style=flat-square)](https://www.npmjs.org/package/@stacks/api-toolkit)

The API Toolkit Library is a comprehensive collection of tools designed by Stacks Labs to simplify
common tasks in API development. This library provides functionalities for database management,
application shutdown handlers, migration helpers, server version management, etc. It aims to
streamline the development process and improve code quality by offering convenient and reusable
modules.

## Installation

You can start by installing the API Toolkit Library using npm:

```bash
npm install @stacks/api-toolkit
```

You should also customize the following ENV variables that control how log messages are displayed:

```env
APPLICATION_NAME=your-api-name
LOG_LEVEL=info
```

## Featured tools

Please see each tool's source directory for additional documentation

### Postgres

* Superclass for connection support and SQL transaction management using
  [postgres.js](https://github.com/porsager/postgres)
* Connection helpers with automatic retry logic, using the standard postgres ENV variables
* Migration tools for migration apply and rollback using
  [node-pg-migrate](https://github.com/salsita/node-pg-migrate)
* Type definitions and conversion helpers for postgres to node type management and viceversa

### Shutdown handlers

* Node.js signal handlers that provide a way to shut down long-running application components
gracefully on unhandled exceptions or interrupt signals.

### Profiler server

* Fastify server that controls a profiler capable of generating:
    * `.cpuprofile` files for CPU usage analysis
    * `.heapsnapshot` files for memory usage analysis

### Logger

* Standardized logger configuration using [pino](https://github.com/pinojs/pino)

### Server versioning

* `api-toolkit-git-info` executable tool to generate API versioning information based on Git branch,
  tag, and latest commit
* Helpers to extract version info to display at runtime or on documentation

### Fastify

* API server creation with CORS, Typebox and Pino logging
* OpenAPI generator plugin with YAML and JSON exports

### Helpers

* Value conversion functions (hex strings, hashes, etc.)
* Timer tools (stopwatch, waiters, etc.)

## License

The API Toolkit Library is released under the Apache 2.0 License. See the LICENSE file for more
details.