testing/readme.md

# @serve.zone/testing

The serve.zone integration test harness exercises real cross-repository behavior that is too stateful for individual package tests: Docker Swarm reconciliation, Cloudly registry flows, Coreflow/Coretraffic routing, Corestore volume and backup APIs, Onebox service lifecycle, App Store templates, and BaseOS image pipeline work.

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

## Purpose

Component repositories keep their fast unit and package tests locally. This repository is for end-to-end smoke scenarios that intentionally cross package boundaries and touch real infrastructure. Most scenarios allocate temporary ports and write under `testing/.nogit/`, but they also create Docker services, networks, containers, images, or local artifacts during execution.

## Scenarios

| Scenario | Command | What it validates |
| --- | --- | --- |
| `corestore-volume-driver` | `pnpm scenario:corestore-volume-driver` | Corestore control API, Docker VolumeDriver protocol, snapshot/restore through `containerarchive`, Coreflow volume mount generation, backup/restore orchestration, and remote replication against a fake Cloudly API. |
| `registry-deploy-on-push` | `pnpm scenario:registry-deploy-on-push` | Cloudly startup with isolated Mongo/S3 helpers, cluster and registry setup, Docker image push, Cloudly metadata update, Coreflow workload provisioning, Coretraffic HTTPS routing, and same-tag redeploy after digest changes. |
| `onebox-basic-lifecycle` | `pnpm scenario:onebox-basic-lifecycle` | Onebox startup in dev mode, SmartProxy ingress, local registry status, workload deploy/remove, HTTP route check, and HTTPS route check with a temporary certificate. |
| `onebox-backup-restore` | `pnpm scenario:onebox-backup-restore` | Onebox service backup creation through ContainerArchive, image-in-backup metadata, clone restore, environment preservation, and cleanup. |
| `onebox-cloudly-appstore-worker` | `pnpm scenario:onebox-cloudly-appstore-worker` | Cloudly App Store template installation through Onebox, MongoDB and MinIO platform resources, worker bootstrap route availability, backup without app image, and platform-resource restore. |
| `baseos-image-pipeline` | `pnpm scenario:baseos-image-pipeline` | CoreBuild BaseOS raw-image job API, S3 artifact upload, Raspberry Pi image customization, WiFi config, SSH key injection, and baserunner environment generation. |

`pnpm test` runs the core host scenarios. `pnpm test:full` adds the Cloudly App Store worker scenario. The BaseOS image pipeline is intentionally separate because it needs image tooling such as `qemu-img`, `guestfish`, and `xz`.

## Host Requirements

- Node.js 22-compatible runtime and `pnpm`.
- Deno for Onebox and BaseOS-related scenarios.
- Docker with Swarm already active for Docker-backed scenarios.
- `openssl` and `curl` for routing and certificate smoke checks.
- `qemu-img`, `guestfish`, and `xz` for `baseos-image-pipeline`.

Bootstrap package dependencies across the workspace before running scenarios:

```bash
pnpm bootstrap:components
```

Run the default scenario set:

```bash
pnpm test
```

Run a single scenario:

```bash
pnpm scenario:corestore-volume-driver
pnpm scenario:registry-deploy-on-push
pnpm scenario:onebox-basic-lifecycle
```

## Vagrant Runner

The included `Vagrantfile` creates an Ubuntu 24.04 VM, mounts the full serve.zone workspace at `/serve.zone`, installs Docker, Node.js, Deno, pnpm, image tooling, and initializes Docker Swarm.

```bash
pnpm vagrant:up
pnpm vagrant:test
pnpm vagrant:destroy
```

Additional Vagrant commands:

```bash
pnpm vagrant:test:baseos
pnpm vagrant:test:full
```

Useful environment variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `SERVEZONE_ROOT` | parent of `testing/` | Workspace path mounted into the VM. |
| `SERVEZONE_VAGRANT_BOX` | `bento/ubuntu-24.04` | Base VM image. |
| `SERVEZONE_VAGRANT_CPUS` | `4` | VM CPU count. |
| `SERVEZONE_VAGRANT_MEMORY` | `8192` | VM memory in MB. |
| `SERVEZONE_KEEP_TEST_ARTIFACTS` | unset | Keeps BaseOS image pipeline artifacts when set. |

## Safety Notes

- Scenarios refuse to overwrite known pre-existing services such as `onebox-smartproxy` when that would risk clobbering a developer's running environment.
- Docker artifacts are labeled or named with scenario-specific smoke IDs where practical, then cleaned up in `finally` blocks.
- Several scenarios change process environment variables temporarily and restore them afterward.
- The harness is intentionally integration-heavy. A failing scenario often prints Docker service logs, task state, route responses, or artifact details before rethrowing.

## Project Map

```text
testing/
├── package.json
├── tsconfig.json
├── Vagrantfile
├── scripts/
│   └── provision-vm.sh
└── scenarios/
    ├── baseos-image-pipeline/
    ├── corestore-volume-driver/
    ├── onebox-backup-restore/
    ├── onebox-basic-lifecycle/
    ├── onebox-cloudly-appstore-worker/
    └── registry-deploy-on-push/
```

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