Files

Juergen Kunz f23c902658 feat(tapbundle_serverside): add network port discovery utilities and migrate file I/O to smartfs; refactor runtimes to use Node fs and SmartFs, update server APIs and bump dependencies

2026-03-03 20:15:59 +00:00

8.9 KiB

Raw Blame History

@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.

8.9 KiB Raw Blame History Unescape Escape