For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What is tsdocker?

tsdocker provides containerized testing environments for npm packages, ensuring your code works consistently across different systems. It's perfect for:

🧪 Testing in clean environments — Every test run starts fresh, just like CI
🔄 Reproducing CI behavior locally — No more "works on my machine" surprises
🐧 Cross-platform development — Develop on macOS/Windows, test on Linux
🚀 Quick validation — Spin up isolated containers for testing without polluting your system

Features

✨ Works Everywhere Docker Does

Docker Toolbox
Native Docker Desktop
Docker-in-Docker (DinD)
Mounted docker.sock scenarios

🔧 Flexible Configuration

Custom base images
Configurable test commands
Environment variable injection via qenv
Optional docker.sock mounting for nested container tests

📦 TypeScript-First

Full TypeScript support with excellent IntelliSense
Type-safe configuration
Modern async/await patterns throughout

Installation

npm install --save-dev @gitzone/tsdocker
# or
pnpm install --save-dev @gitzone/tsdocker

Quick Start

1. Configure Your Project

Create an npmextra.json file in your project root:

{
  "npmdocker": {
    "baseImage": "hosttoday/ht-docker-node:npmts",
    "command": "npmci test stable",
    "dockerSock": false
  }
}

2. Run Your Tests

npx tsdocker

That's it! tsdocker will:

✅ Verify Docker is available
🏗️ Build a test container with your specified base image
📂 Mount your project directory
🚀 Execute your test command
🧹 Clean up automatically

Configuration Options

Option	Type	Description
`baseImage`	`string`	Docker image to use as the test environment base
`command`	`string`	CLI command to execute inside the container
`dockerSock`	`boolean`	Whether to mount `/var/run/docker.sock` for Docker-in-Docker scenarios

Environment Variables

If you have a qenv.yml file in your project, tsdocker automatically loads and injects those environment variables into your test container.

Example qenv.yml:

demoKey: demoValue
API_KEY: your-key-here

CLI Commands

Standard Test Run

tsdocker

Runs your configured test command in a fresh Docker container.

Clean Docker Environment

tsdocker clean --all

⚠️ WARNING: This aggressively cleans your Docker environment by:

Killing all running containers
Removing all stopped containers
Removing dangling images
Removing all images
Removing dangling volumes

Use with caution!

VSCode in Docker

tsdocker vscode

Launches a containerized VS Code instance accessible via browser at testing-vscode.git.zone:8443.

Speed Test

tsdocker speedtest

Runs a network speed test inside a Docker container.

Advanced Usage

Docker-in-Docker Testing

If you need to run Docker commands inside your test container (e.g., testing Docker-related tools):

{
  "npmdocker": {
    "baseImage": "docker:latest",
    "command": "docker run hello-world",
    "dockerSock": true
  }
}

Setting "dockerSock": true mounts the host's Docker socket into the container.

Custom Base Images

You can use any Docker image as your base:

{
  "npmdocker": {
    "baseImage": "node:20-alpine",
    "command": "npm test"
  }
}

Popular choices:

node:20 — Official Node.js images
node:20-alpine — Lightweight Alpine-based images
hosttoday/ht-docker-node:npmts — Pre-configured with npmts tooling

CI Integration

tsdocker automatically detects CI environments (via CI=true env var) and adjusts behavior:

Skips mounting project directory in CI (assumes code is already in container)
Optimizes for CI execution patterns

Why tsdocker?

The Problem

Local development environments drift over time. You might have:

Stale global packages
Modified system configurations
Cached dependencies
Different Node.js versions

Your tests pass locally but fail in CI — or vice versa.

The Solution

tsdocker ensures every test run happens in a clean, reproducible environment, just like your CI pipeline. This means:

✅ Consistent behavior between local and CI ✅ No dependency pollution between test runs ✅ Easy cross-platform testing ✅ Reproducible bug investigations

TypeScript Usage

tsdocker is built with TypeScript and provides full type definitions:

import { IConfig } from '@gitzone/tsdocker/dist/tsdocker.config';

const config: IConfig = {
  baseImage: 'node:20',
  command: 'npm test',
  dockerSock: false,
  keyValueObject: {
    NODE_ENV: 'test'
  }
};

Requirements

Docker: Docker must be installed and accessible via CLI
Node.js: Version 14 or higher recommended

How It Works

Under the hood, tsdocker:

📋 Reads your npmextra.json configuration
🔍 Optionally loads environment variables from qenv.yml
🐳 Generates a temporary Dockerfile
🏗️ Builds a Docker image with your base image
📦 Mounts your project directory (unless in CI)
▶️ Runs your test command inside the container
📊 Captures the exit code
🧹 Cleans up containers and images
✅ Exits with the same code as your tests

Troubleshooting

"docker not found on this machine"

Make sure Docker is installed and the docker command is in your PATH:

docker --version

Tests fail in container but work locally

This often indicates environment-specific issues. Check:

Are all dependencies in package.json? (not relying on global packages)
Does your code have hardcoded paths?
Are environment variables set correctly?

Permission errors with docker.sock

If using dockerSock: true, ensure your user has permissions to access /var/run/docker.sock:

sudo usermod -aG docker $USER
# Then log out and back in

Examples

Basic npm test

{
  "npmdocker": {
    "baseImage": "node:20",
    "command": "npm test"
  }
}

Using npmci for multiple Node versions

{
  "npmdocker": {
    "baseImage": "hosttoday/ht-docker-node:npmts",
    "command": "npmci test stable"
  }
}

Testing Docker-based tools

{
  "npmdocker": {
    "baseImage": "docker:latest",
    "command": "sh -c 'docker version && docker ps'",
    "dockerSock": true
  }
}

Performance Tips

🚀 Use specific base images: node:20-alpine is much faster to pull than node:latest 🚀 Layer caching: Docker caches image layers — your base image only downloads once 🚀 Prune regularly: Run docker system prune periodically to reclaim disk space

Migration from @gitzone/npmdocker

This package was previously published as @gitzone/npmdocker. The scope has been updated to @gitzone/tsdocker for better naming consistency. Functionality remains the same.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

readme.md

@gitzone/tsdocker

Issue Reporting and Security