tstest/ts_tapbundle_serverside

@git.zone/tstest/tapbundle_serverside

🔧 Server-side testing utilities for Node.js runtime tests

Installation

# tapbundle_serverside is included as part of @git.zone/tstest
pnpm install --save-dev @git.zone/tstest

Issue Reporting and Security

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.

Overview

@git.zone/tstest/tapbundle_serverside provides server-side testing utilities exclusively for Node.js runtime. These tools make it trivial to spin up test infrastructure — free ports, HTTPS certificates, ephemeral databases, S3 storage, shell commands, and environment variable management.

Key Features

• 🌐 Network Utilities — Find free ports and port ranges for test servers
• 🔒 HTTPS Certificates — Generate self-signed certificates for testing
• 💻 Shell Commands — Execute bash commands during tests
• 🔐 Environment Variables — On-demand environment variable loading with qenv
• 🗄️ MongoDB Testing — Create ephemeral MongoDB instances
• 📦 S3 Storage Testing — Create local S3-compatible storage
• 📁 Test File Management — Download and manage test assets

Basic Usage

import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';
import { tap, expect } from '@git.zone/tstest/tapbundle';

tap.test('should start server on free port', async () => {
  const port = await tapNodeTools.findFreePort();
  // start your server on `port`
});

export default tap.start();

API Reference

tapNodeTools

The main singleton instance providing all Node.js-specific utilities.

---

🌐 Network Utilities

findFreePort(options?)

Find a single free port on the local machine.

// Default: random free port in range 3000–60000
const port = await tapNodeTools.findFreePort();

// Custom range
const port = await tapNodeTools.findFreePort({
  startPort: 8000,
  endPort: 9000,
});

// With exclusions and sequential scan
const port = await tapNodeTools.findFreePort({
  startPort: 3000,
  endPort: 60000,
  randomize: false,   // default: true
  exclude: [8080, 8443],
});

Options:

Option	Type	Default	Description
startPort	number	3000	Start of port range (inclusive)
endPort	number	60000	End of port range (inclusive)
randomize	boolean	true	Pick a random port vs first available
exclude	number[]	[]	Ports to skip

Returns: Promise<number> — Throws if no free port is found.

findFreePorts(count, options?)

Find multiple distinct free ports. Each found port is automatically excluded from subsequent searches, guaranteeing all returned ports are unique.

const [httpPort, wsPort, adminPort] = await tapNodeTools.findFreePorts(3);

// With custom range
const ports = await tapNodeTools.findFreePorts(2, {
  startPort: 10000,
  endPort: 20000,
});

Parameters:

• count — Number of ports to find
• options — Same as findFreePort()

Returns: Promise<number[]> — Array of distinct free ports.

findFreePortRange(count, options?)

Find consecutive free ports (e.g., [4000, 4001, 4002]). Useful when you need a contiguous block.

const ports = await tapNodeTools.findFreePortRange(3, {
  startPort: 20000,
  endPort: 30000,
});
// ports = [N, N+1, N+2] where all three are free

Options:

Option	Type	Default	Description
startPort	number	3000	Start of search range
endPort	number	60000	End of search range
exclude	number[]	[]	Ports to skip

Returns: Promise<number[]> — Array of consecutive free ports.

---

🔒 HTTPS Certificates

createHttpsCert(commonName?, allowSelfSigned?)

Generate a self-signed HTTPS certificate for testing secure connections.

const { key, cert } = await tapNodeTools.createHttpsCert('localhost', true);

// Use with Node.js https module
const server = https.createServer({ key, cert }, handler);
server.listen(port);

Parameters:

• commonName (default: 'localhost') — Certificate common name
• allowSelfSigned (default: true) — Sets NODE_TLS_REJECT_UNAUTHORIZED=0

Returns: Promise<{ key: string; cert: string }> — PEM-encoded key and certificate.

---

💻 Shell Commands

runCommand(command)

Execute a bash command and return the result.

const result = await tapNodeTools.runCommand('ls -la');
console.log(result.exitCode);
console.log(result.stdout);

---

🔐 Environment Variables

getQenv()

Get the qenv instance for managing environment variables from .nogit/ directory.

const qenv = await tapNodeTools.getQenv();

getEnvVarOnDemand(envVarName)

Request an environment variable. If not available, qenv will prompt for it and store it securely.

const apiKey = await tapNodeTools.getEnvVarOnDemand('GITHUB_API_KEY');
// If not set, prompts interactively and stores in .nogit/.env

---

🗄️ Database Testing

createSmartmongo()

Create an ephemeral MongoDB instance. Automatically started and ready to use.

const mongo = await tapNodeTools.createSmartmongo();
// ... run database tests ...
await mongo.stop();

Uses @push.rocks/smartmongo.

---

📦 Storage Testing

createSmarts3()

Create a local S3-compatible storage instance for testing.

const s3 = await tapNodeTools.createSmarts3();
// ... run storage tests ...
await s3.stop();

Default config: port 3003, clean slate enabled. Uses @push.rocks/smarts3.

---

📁 Test File Provider

testFileProvider.getDockerAlpineImageAsLocalTarball()

Download the Alpine Linux Docker image as a tarball for testing.

const tarballPath = await tapNodeTools.testFileProvider.getDockerAlpineImageAsLocalTarball();
// Path: ./.nogit/testfiles/alpine.tar

Runtime Requirements

⚠️ Node.js only. All utilities in this module require Node.js. Import only in .node.ts test files.

test/mytest.node.ts          ✅ Correct — Node.js only
test/mytest.ts               ✅ Correct — defaults to Node.js
test/mytest.all.ts           ❌ Will fail in Deno/Bun/Chromium

Dependencies

• @push.rocks/smartnetwork — Port discovery
• @push.rocks/qenv — Environment variable management
• @push.rocks/smartshell — Shell command execution
• @push.rocks/smartcrypto — Certificate generation
• @push.rocks/smartmongo — MongoDB testing
• @push.rocks/smarts3 — S3 storage testing
• @push.rocks/smartfile — File operations
• @push.rocks/smartrequest — HTTP requests

License and Legal Information

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

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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.