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 https://community.foss.global/. This is the central community hub for all issue reporting. Developers who want to sign a 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 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

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.

Company Information

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

For any legal inquiries or if you require 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.