# @git.zone/tstest/tapbundle_serverside

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

## Installation

```bash
# 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/](https://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/](https://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

```typescript
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.

```typescript
// 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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
const qenv = await tapNodeTools.getQenv();
```

#### `getEnvVarOnDemand(envVarName)`

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

```typescript
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.

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

Uses [@push.rocks/smartmongo](https://code.foss.global/push.rocks/smartmongo).

---

### 📦 Storage Testing

#### `createSmarts3()`

Create a local S3-compatible storage instance for testing.

```typescript
const s3 = await tapNodeTools.createSmartStorage();
// ... run storage tests ...
await s3.stop();
```

Default config: port 3003, clean slate enabled. Uses [@push.rocks/smartstorage](https://code.foss.global/push.rocks/smartstorage).

---

### 📁 Test File Provider

#### `testFileProvider.getDockerAlpineImageAsLocalTarball()`

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

```typescript
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](https://code.foss.global/push.rocks/smartnetwork) — Port discovery
- [@push.rocks/qenv](https://code.foss.global/push.rocks/qenv) — Environment variable management
- [@push.rocks/smartshell](https://code.foss.global/push.rocks/smartshell) — Shell command execution
- [@push.rocks/smartcrypto](https://code.foss.global/push.rocks/smartcrypto) — Certificate generation
- [@push.rocks/smartmongo](https://code.foss.global/push.rocks/smartmongo) — MongoDB testing
- [@push.rocks/smartstorage](https://code.foss.global/push.rocks/smartstorage) — S3 storage testing
- [@push.rocks/smartfile](https://code.foss.global/push.rocks/smartfile) — File operations
- [@push.rocks/smartrequest](https://code.foss.global/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](../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.