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

Overview

@git.zone/tstest/tapbundle_serverside provides server-side testing utilities exclusively for Node.js runtime. These tools enable shell command execution, environment variable management, HTTPS certificate generation, database testing, object storage testing, and test asset management - all functionality that only makes sense on the server-side.

Key Features

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

Basic Usage

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

tap.test('should use server-side tools', async () => {
  // Execute shell commands on the server-side
  const result = await tapNodeTools.runCommand('echo "hello"');
  console.log(result);
});

export default tap.start();

API Reference

tapNodeTools

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

Environment Variables

getQenv()

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

const qenv = await tapNodeTools.getQenv();
// qenv will load from .env files in .nogit/ directory

getEnvVarOnDemand(envVarName)

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

tap.test('should get API key', async () => {
  const apiKey = await tapNodeTools.getEnvVarOnDemand('GITHUB_API_KEY');
  // If GITHUB_API_KEY is not set, qenv will prompt for it
  // The value is stored in .nogit/.env for future use
});

Use Cases:

• API keys for integration tests
• Database credentials
• Service endpoints
• Any sensitive configuration needed for testing

Shell Commands

runCommand(command)

Execute a bash command and return the result.

tap.test('should execute shell commands', async () => {
  const result = await tapNodeTools.runCommand('ls -la');
  console.log(result.stdout);
});

Use Cases:

• Setup test environment
• Execute CLI tools
• File system operations
• Process management

HTTPS Certificates

createHttpsCert(commonName?, allowSelfSigned?)

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

tap.test('should create HTTPS server', async () => {
  const { key, cert } = await tapNodeTools.createHttpsCert('localhost', true);

  // Use with Node.js https module
  const server = https.createServer({ key, cert }, (req, res) => {
    res.end('Hello Secure World');
  });

  server.listen(3000);
});

Parameters:

• commonName (optional): Certificate common name, default: 'localhost'
• allowSelfSigned (optional): Allow self-signed certificates by setting NODE_TLS_REJECT_UNAUTHORIZED=0, default: true

Returns:

• key: PEM-encoded private key
• cert: PEM-encoded certificate

Use Cases:

• Testing HTTPS servers
• Testing secure WebSocket connections
• Testing certificate validation logic
• Mocking secure external services

Database Testing

createSmartmongo()

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

import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';

tap.test('should use MongoDB', async () => {
  const mongoInstance = await tapNodeTools.createSmartmongo();

  // Use the MongoDB instance
  const db = await mongoInstance.getDatabase('testdb');
  const collection = await db.getCollection('users');

  await collection.insertOne({ name: 'Alice', age: 30 });
  const user = await collection.findOne({ name: 'Alice' });

  expect(user.age).toEqual(30);

  // Cleanup (optional - instance will be cleaned up automatically)
  await mongoInstance.stop();
});

export default tap.start();

Features:

• Ephemeral instance (starts fresh)
• Automatic cleanup
• Full MongoDB API via @push.rocks/smartmongo

Use Cases:

• Testing database operations
• Integration tests with MongoDB
• Testing data models
• Schema validation tests

Storage Testing

createSmarts3()

Create a local S3-compatible storage instance for testing object storage operations.

import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';

tap.test('should use S3 storage', async () => {
  const s3Instance = await tapNodeTools.createSmarts3();

  // Use the S3 instance (MinIO-compatible API)
  const bucket = await s3Instance.createBucket('test-bucket');
  await bucket.putObject('file.txt', Buffer.from('Hello S3'));
  const file = await bucket.getObject('file.txt');

  expect(file.toString()).toEqual('Hello S3');

  // Cleanup
  await s3Instance.stop();
});

export default tap.start();

Configuration:

• Port: 3003 (default)
• Clean slate: true (starts fresh each time)
• Full S3-compatible API via @push.rocks/smarts3

Use Cases:

• Testing file uploads/downloads
• Testing object storage operations
• Testing backup/restore logic
• Mocking cloud storage

TestFileProvider

Utility for downloading and managing test assets.

getDockerAlpineImageAsLocalTarball()

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

import { tapNodeTools } from '@git.zone/tstest/tapbundle_serverside';

tap.test('should provide docker image', async () => {
  const tarballPath = await tapNodeTools.testFileProvider.getDockerAlpineImageAsLocalTarball();

  // Use the tarball path
  // Path: ./.nogit/testfiles/alpine.tar

  expect(tarballPath).toMatch(/alpine\.tar$/);
});

export default tap.start();

Features:

• Downloads from https://code.foss.global/testassets/docker
• Caches in .nogit/testfiles/ directory
• Returns local file path

Use Cases:

• Testing Docker operations
• Testing container deployment
• Testing image handling logic

Path Utilities

The module exports useful path constants:

import * as paths from '@git.zone/tstest/tapbundle_serverside/paths';

console.log(paths.cwd);          // Current working directory
console.log(paths.testFilesDir); // ./.nogit/testfiles/

Patterns and Best Practices

Testing with External Services

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

tap.describe('User Service Integration', () => {
  let mongoInstance;
  let db;

  tap.beforeEach(async () => {
    mongoInstance = await tapNodeTools.createSmartmongo();
    db = await mongoInstance.getDatabase('testdb');
  });

  tap.test('should create user', async () => {
    const users = await db.getCollection('users');
    await users.insertOne({ name: 'Bob', email: 'bob@example.com' });

    const user = await users.findOne({ name: 'Bob' });
    expect(user.email).toEqual('bob@example.com');
  });

  tap.afterEach(async () => {
    await mongoInstance.stop();
  });
});

export default tap.start();

Testing HTTPS Servers

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

tap.test('should serve over HTTPS', async () => {
  const { key, cert } = await tapNodeTools.createHttpsCert();

  const server = https.createServer({ key, cert }, (req, res) => {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Secure Response');
  });

  await new Promise((resolve) => {
    server.listen(8443, () => resolve(undefined));
  });

  // Test the server
  const response = await fetch('https://localhost:8443');
  const text = await response.text();
  expect(text).toEqual('Secure Response');

  // Cleanup
  server.close();
});

export default tap.start();

Environment-Dependent Tests

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

tap.test('should authenticate with GitHub', async () => {
  const githubToken = await tapNodeTools.getEnvVarOnDemand('GITHUB_TOKEN');

  // Use the token for API calls
  const response = await fetch('https://api.github.com/user', {
    headers: {
      Authorization: `Bearer ${githubToken}`
    }
  });

  expect(response.ok).toBeTruthy();
});

export default tap.start();

Runtime Requirements

⚠️ Server-Side Only (Node.js): All utilities in this module are designed exclusively for server-side testing in Node.js runtime. They provide functionality like shell command execution, file system operations, and process management that only make sense on the server.

NOT available in:

• Browser environments
• Deno runtime
• Bun runtime

Important: Import tapbundle_serverside only in tests that run exclusively on the server-side (.node.ts test files). For cross-runtime tests, these utilities will fail in non-Node environments.

File Naming

Use Node.js-specific file naming when using these utilities:

test/mytest.node.ts              ✅ Node.js only
test/mytest.node+deno.ts         ❌ Will fail in Deno
test/mytest.browser+node.ts      ⚠️ Browser won't have access to these tools

Dependencies

This module uses the following packages:

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

Legal

This project is licensed under MIT.

© 2025 Task Venture Capital GmbH. All rights reserved.