Development

April 28, 2026 · View on GitHub

Prerequisites

# Install amplifier-gitea if you don't have it
uv tool install git+https://github.com/microsoft/amplifier-bundle-gitea@main

# Optional: for .local hostname support
sudo apt install avahi-daemon avahi-utils

Setup

git clone https://github.com/microsoft/amplifier-bundle-digital-twin-universe.git
cd amplifier-bundle-digital-twin-universe
uv sync

Running the CLI locally

uv run amplifier-digital-twin --help
uv run amplifier-digital-twin launch amplifier-user-sim

Manual Verification

For a full amplifier-user-sim walkthrough that mirrors the same repo changes used by the end-to-end test, see manual_verification.md.

Tests

Note: Integration tests clean up only the containers they created. Each test fixture registers its instance ID at launch time, and the session-scoped cleanup fixture force-deletes only those registered IDs. Environments created by other sessions or manual use are not affected.

Tests invoke amplifier-digital-twin as a subprocess via uv run, exactly as a user would on their machine. No in-process test runners or mocks.

The suite is organized by tier under tests/. See ../tests/README.md for the full layout and per-file prerequisites.

# Unit tests — no external deps, run by default
uv run pytest tests/unit/

# Lifecycle smoke tests — requires Incus running
uv run pytest tests/integration/ --run-integration -v

E2E Tests

The end-to-end coverage is split so you can run the fastest useful suite first.

File operations test

Exercises file-push, file-pull, and provision.files with a minimal container. Pushes files in, pulls them back, verifies content integrity.

Prerequisites:

  • Incus running
uv run pytest tests/e2e/features/test_file_ops.py --run-e2e -v -s

Exec streaming test

Exercises exec --stream with a minimal container. Verifies real-time stdout/stderr passthrough, exit code propagation, and backward compatibility with the default JSON mode.

Prerequisites:

  • Incus running
uv run pytest tests/e2e/features/test_exec_stream.py --run-e2e -v -s

Fast PyPI override test

Exercises wheel_from_git with a tiny temporary package repo.

Prerequisites:

  • Incus running
uv run pytest tests/e2e/features/test_pypi.py --run-e2e -v -s

Fast single-module rewrite test

Launches amplifier-user-sim-single-module, mirrors amplifier-module-provider-anthropic into Gitea, pushes a marker change on top, and verifies the rewritten provider is loaded.

Prerequisites:

  • Incus running
  • Docker running
  • amplifier-gitea installed on PATH
  • GitHub token (GH_TOKEN, GITHUB_TOKEN, or gh auth login)
uv run pytest tests/e2e/profiles/test_amplifier_user_sim_single_module.py --run-e2e -v -s

Full amplifier-user-sim end-to-end test

Mirrors both amplifier-core and amplifier-module-provider-anthropic into Gitea, pushes local changes on top, launches amplifier-user-sim, and verifies:

  • the installed Amplifier tool environment uses the overridden amplifier-core wheel
  • running Amplifier loads the rewritten amplifier-module-provider-anthropic source and completes a real Anthropic-backed run
  • after pushing updated mutations and running amplifier-digital-twin update, the new amplifier-core version and new provider marker are live without relaunching

Prerequisites:

  • Incus running
  • Docker running
  • amplifier-gitea installed on PATH
  • GitHub token (GH_TOKEN, GITHUB_TOKEN, or gh auth login)
  • ANTHROPIC_API_KEY
uv run pytest tests/e2e/profiles/test_amplifier_user_sim.py --run-e2e -v -s

amplifier-chat web UI test

Launches amplifier-chat, verifies the health endpoint, chat UI, and LLM execution are reachable from the host via the Incus proxy device. Also exercises amplifier-digital-twin update to restart the service and confirm it remains healthy afterward.

Prerequisites:

  • Incus running
  • ANTHROPIC_API_KEY
uv run pytest tests/e2e/profiles/test_amplifier_chat.py --run-e2e -v -s

Hostname mDNS registration test

Launches docker-in-incus with a custom hostname, verifies .local resolution via Avahi, and confirms cleanup on destroy.

Prerequisites:

  • Incus running
  • avahi-daemon running + avahi-utils installed
uv run pytest tests/e2e/features/test_hostname.py --run-e2e -v -s

To run all end-to-end suites:

uv run pytest tests/e2e/ --run-e2e -v -s

Or run just the cross-cutting feature tests (no API keys, no Gitea):

uv run pytest tests/e2e/features/ --run-e2e -v -s