virtualmcp

package
v0.11.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 12, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

README

VirtualMCPServer E2E Tests

This directory contains end-to-end tests for the VirtualMCPServer controller that run against a real Kubernetes cluster.

Prerequisites

  • A Kubernetes cluster with the ToolHive operator installed
  • kubectl configured to access the cluster
  • The VirtualMCPServer CRDs installed

Note: The Ginkgo CLI is automatically installed by the task commands when running tests.

Running the Tests

The easiest way to run the tests is using the task command from the operator directory, which will:

  1. Create a Kind cluster
  2. Install CRDs
  3. Deploy the operator
  4. Run all tests from test/e2e/thv-operator/virtualmcp (including setup)
  5. Clean up the cluster
# Run from the project root
task thv-operator-e2e-test
Manual Testing

The tests will:

  • Use the kubeconfig from $KUBECONFIG or ~/.kube/config
  • Create all necessary resources (MCPGroup, MCPServers, VirtualMCPServer)
  • Run comprehensive MCP protocol tests
  • Clean up resources after completion
cd test/e2e/thv-operator/virtualmcp
ginkgo -v
Customizing Test Parameters

You can customize the kubeconfig path using the KUBECONFIG environment variable:

export KUBECONFIG="/path/to/kubeconfig"
ginkgo -v
Running Specific Tests
# Run only discovered mode tests
ginkgo -v --focus="Discovered Mode"

# Run tests and get verbose output
ginkgo -vv

Test Structure

Files
  • suite_test.go - Ginkgo test suite setup with kubeconfig loading
  • virtualmcp_discovered_mode_test.go - Tests VirtualMCPServer with discovered mode aggregation
  • helpers.go - Common helper functions for interacting with Kubernetes resources
  • README.md - This file
Test Descriptions
Discovered Mode Tests (virtualmcp_discovered_mode_test.go)

Comprehensive E2E tests for VirtualMCPServer in discovered mode, which automatically discovers and aggregates tools from backend MCP servers in a group:

  • Creates two backend MCPServers (fetch and osv) both using streamable-http transport
  • Verifies VirtualMCPServer aggregates tools from all backends in the group
  • Tests tool calls through the VirtualMCPServer proxy
  • Validates discovered mode configuration and backend discovery
  • Uses prefix conflict resolution strategy to namespace tools from different backends

Environment Variables

Variable Description Default
KUBECONFIG Path to kubeconfig file ~/.kube/config

Adding New Tests

To add new test cases:

  1. Create a new test file following the naming pattern *_test.go
  2. Use the shared k8sClient and ctx variables from suite_test.go
  3. Use helper functions from helpers.go when possible
  4. Follow Ginkgo BDD style with Describe, Context, and It blocks

Example:

var _ = Describe("VirtualMCPServer Feature", func() {
    Context("when testing feature X", func() {
        It("should behave as expected", func() {
            // Test implementation
        })
    })
})

Troubleshooting

Tests fail with "kubeconfig file should exist"

Ensure your KUBECONFIG environment variable points to a valid kubeconfig file, or that ~/.kube/config exists.

Tests fail with "VirtualMCPServer should exist"

Make sure:

  1. The ToolHive operator is running in your cluster
  2. The VirtualMCPServer CRDs are installed
  3. The tests create their own VirtualMCPServer resources for testing
Tests timeout waiting for resources

Check:

  1. The operator is running: kubectl get pods -n toolhive-system
  2. The operator logs for errors: kubectl logs -n toolhive-system -l app.kubernetes.io/name=thv-operator
  3. The VirtualMCPServer status: kubectl get virtualmcpserver -n <namespace> <name> -o yaml

Documentation

Overview

Package virtualmcp provides helper functions for VirtualMCP E2E tests.

Index

Constants

View Source 
const InstrumentedBackendScript = `` /* 1379-byte string literal not displayed */

InstrumentedBackendScript is an instrumented backend script that tracks Bearer tokens

View Source 
const MockOIDCServerHTTPScript = `` /* 1627-byte string literal not displayed */

MockOIDCServerHTTPScript is a mock OIDC server script with HTTP (for testing with private IPs)

View Source 
const ParameterizedOIDCServerScript = `` /* 2737-byte string literal not displayed */

ParameterizedOIDCServerScript is a minimal Python OIDC server that issues RSA-signed RS256 JWTs with a caller-controlled subject.

Usage: POST /token?subject=alice → returns {"access_token": "<jwt>", ...} The subject defaults to "test-user" when the query parameter is omitted.

The issuer is derived from the service name: the server reads the HOST environment variable set by the caller via the ISSUER constant below. Tests that deploy this script must set the correct issuer URL in the VirtualMCPServer InlineOIDCConfig.Issuer field.

Variables

This section is empty.

Functions

func CleanupFakeEmbeddingServer added in v0.11.3 

func CleanupFakeEmbeddingServer(ctx context.Context, c client.Client, name, namespace string)

CleanupFakeEmbeddingServer removes the fake embedding server Deployment and Service.

func CleanupMockHTTPServer added in v0.6.14 

func CleanupMockHTTPServer(ctx context.Context, c client.Client, name, namespace string)

CleanupMockHTTPServer removes the mock HTTP server resources

func CleanupMockServer 

func CleanupMockServer(ctx context.Context, c client.Client, namespace, serverName, tlsSecretName string)

CleanupMockServer cleans up a mock server deployment, service, and optionally its TLS secret

func CreateMCPGroupAndWait added in v0.6.11 

func CreateMCPGroupAndWait(
	ctx context.Context,
	c client.Client,
	name, namespace, description string,
	timeout, pollingInterval time.Duration,
) *mcpv1alpha1.MCPGroup

CreateMCPGroupAndWait creates an MCPGroup and waits for it to become ready. Returns the created MCPGroup after it reaches Ready phase.

func CreateMCPServerAndWait added in v0.6.11 

func CreateMCPServerAndWait(
	ctx context.Context,
	c client.Client,
	name, namespace, groupRef, image string,
	timeout, pollingInterval time.Duration,
) *mcpv1alpha1.MCPServer

CreateMCPServerAndWait creates an MCPServer with the specified image and waits for it to be running. Returns the created MCPServer after it reaches Running phase.

func CreateMultipleMCPServersInParallel added in v0.6.13 

func CreateMultipleMCPServersInParallel(
	ctx context.Context,
	c client.Client,
	backends []BackendConfig,
	timeout, pollingInterval time.Duration,
)

CreateMultipleMCPServersInParallel creates multiple MCPServers concurrently and waits for all to be running. This significantly reduces test setup time compared to sequential creation.

func DeployFakeEmbeddingServer added in v0.11.3 

func DeployFakeEmbeddingServer(
	ctx context.Context,
	c client.Client,
	name, namespace string,
	timeout, pollingInterval time.Duration,
) string

DeployFakeEmbeddingServer deploys a lightweight fake embedding server that mimics the TEI API. This avoids pulling the heavyweight TEI container image while satisfying the optimizer's embedding service requirement. Returns the in-cluster service URL (http://<name>.<namespace>.svc.cluster.local:8080).

func DeployInstrumentedBackendServer 

func DeployInstrumentedBackendServer(ctx context.Context, c client.Client, namespace, serverName string)

DeployInstrumentedBackendServer deploys a backend server that logs all headers

func DeployMockOIDCServerHTTP 

func DeployMockOIDCServerHTTP(ctx context.Context, c client.Client, namespace, serverName string)

DeployMockOIDCServerHTTP deploys a mock OIDC server with HTTP (for testing)

func DeployParameterizedOIDCServer added in v0.11.3 

func DeployParameterizedOIDCServer(
	ctx context.Context,
	c client.Client,
	name, namespace string,
	timeout, pollingInterval time.Duration,
) (issuerURL string, allocatedNodePort int32, cleanup func())

DeployParameterizedOIDCServer deploys an in-cluster mock OIDC server that issues RSA-signed JWTs with a caller-controlled subject claim (via POST /token?subject=<name>). The server is exposed via a fixed NodePort so the test process (running outside the cluster) can reach it.

Returns the in-cluster issuer URL (http://<name>.<namespace>.svc.cluster.local) and a cleanup function that removes all created resources.

func GetInstrumentedBackendStats 

func GetInstrumentedBackendStats(ctx context.Context, c client.Client, namespace, serviceName string) (map[string]int, error)

GetInstrumentedBackendStats queries the /stats endpoint of the instrumented backend

func GetMCPGroupBackends 

func GetMCPGroupBackends(ctx context.Context, c client.Client, groupName, namespace string) ([]mcpv1alpha1.MCPServer, error)

GetMCPGroupBackends returns the list of backend MCPServers in an MCPGroup Note: MCPGroup status contains the list of servers in the group

func GetMCPServerDeployment added in v0.8.3 

func GetMCPServerDeployment(ctx context.Context, c client.Client, serverName, namespace string) *appsv1.Deployment

GetMCPServerDeployment retrieves the deployment for an MCPServer by name. MCPServer deployments use the same name as the MCPServer resource.

func GetMCPServerStatefulSet added in v0.8.3 

func GetMCPServerStatefulSet(ctx context.Context, c client.Client, serverName, namespace string) *appsv1.StatefulSet

GetMCPServerStatefulSet retrieves the StatefulSet for an MCPServer by name. MCPServer StatefulSets use the same name as the MCPServer resource for the workload pods.

func GetMockOIDCStats 

func GetMockOIDCStats(ctx context.Context, c client.Client, namespace, serviceName string) (map[string]int, error)

GetMockOIDCStats queries the /stats endpoint of the mock OIDC server

func GetPodLogs added in v0.6.10 

func GetPodLogs(ctx context.Context, podName, namespace, containerName string) (string, error)

GetPodLogs returns logs from a specific pod and container

func GetPodLogsForDeployment 

func GetPodLogsForDeployment(ctx context.Context, c client.Client, namespace, deploymentName string) string

GetPodLogsForDeployment returns logs from pods for a deployment (for debugging)

func GetServiceStats 

func GetServiceStats(ctx context.Context, c client.Client, namespace, serviceName string, port int) (string, error)

GetServiceStats queries the /stats endpoint of a service and returns the stats

func GetVMCPNodePort added in v0.6.11 

func GetVMCPNodePort(
	ctx context.Context,
	c client.Client,
	vmcpServerName, namespace string,
	timeout, pollingInterval time.Duration,
) int32

GetVMCPNodePort waits for the VirtualMCPServer service to have a NodePort assigned and verifies the port is accessible.

func GetVirtualMCPServerPods 

func GetVirtualMCPServerPods(ctx context.Context, c client.Client, vmcpServerName, namespace string) (*corev1.PodList, error)

GetVirtualMCPServerPods returns all pods for a VirtualMCPServer

func GetVirtualMCPServerStatus 

func GetVirtualMCPServerStatus(
	ctx context.Context,
	c client.Client,
	name, namespace string,
) (*mcpv1alpha1.VirtualMCPServerStatus, error)

GetVirtualMCPServerStatus returns the current status of a VirtualMCPServer

func HasCondition 

func HasCondition(vmcpServer *mcpv1alpha1.VirtualMCPServer, conditionType string, expectedStatus string) bool

HasCondition checks if a VirtualMCPServer has a specific condition type with expected status

func InitializeMCPClientWithRetries added in v0.6.14 

func InitializeMCPClientWithRetries(
	serverURL string,
	timeout time.Duration,
	opts ...transport.StreamableHTTPCOption,
) *mcpclient.Client

InitializeMCPClientWithRetries creates and initializes an MCP client with proper retry handling. It creates a NEW client for each retry attempt to avoid stale session state issues. Returns the initialized client. Caller is responsible for calling Close() on the client.

func TestToolListing added in v0.6.12 

func TestToolListing(vmcpNodePort int32, clientName string) []mcp.Tool

TestToolListing is a shared helper that creates an MCP client and lists tools. Returns the list of tools for further assertions.

func TestToolListingAndCall added in v0.6.12 

func TestToolListingAndCall(vmcpNodePort int32, clientName string, toolNamePattern string, testInput string)

TestToolListingAndCall is a shared helper that creates an MCP client, lists tools, finds a tool matching the pattern, calls it, and verifies the response. This eliminates the duplicate "create client → list → call" pattern found in most tests.

func ToolsContainAll added in v0.11.3 

func ToolsContainAll(tools []mcp.Tool, expectedNames ...string) error

ToolsContainAll checks if the tool list contains all expected tool names (exact match). Returns an error listing missing tools, or nil if all are found.

func ToolsContainSubstring added in v0.11.3 

func ToolsContainSubstring(tools []mcp.Tool, substrings ...string) error

ToolsContainSubstring checks if the tool list contains at least one tool whose name contains each of the given substrings. Returns an error if any substring has no matching tool.

func ToolsHavePrefix added in v0.11.3 

func ToolsHavePrefix(tools []mcp.Tool, prefixes ...string) error

ToolsHavePrefix checks if there is at least one tool with each of the given prefixes. Returns an error listing missing prefixes, or nil if all are found.

func VMCPServiceName added in v0.6.11 

func VMCPServiceName(vmcpServerName string) string

VMCPServiceName returns the Kubernetes service name for a VirtualMCPServer

func WaitForCondition 

func WaitForCondition(
	ctx context.Context,
	c client.Client,
	name, namespace string,
	conditionType string,
	expectedStatus string,
	timeout time.Duration,
	pollingInterval time.Duration,
)

WaitForCondition waits for a VirtualMCPServer to have a specific condition

func WaitForExpectedTools added in v0.11.3 

func WaitForExpectedTools(
	vmcpNodePort int32,
	clientName string,
	validateTools func([]mcp.Tool) error,
	timeout ...time.Duration,
) *mcp.ListToolsResult

WaitForExpectedTools creates MCP sessions with retry until the validateTools function returns nil (all expected tools are present). Returns the final tool list. This is essential for avoiding flaky tests caused by session-scoped tool discovery race conditions: when a backend isn't fully ready, it's silently skipped, producing incomplete tool lists. Each retry creates a new MCP session to trigger fresh discovery.

func WaitForExpectedToolsWithAuth added in v0.11.3 

func WaitForExpectedToolsWithAuth(
	vmcpNodePort int32,
	timeout time.Duration,
	validateTools func([]mcp.Tool) error,
	opts ...transport.StreamableHTTPCOption,
) (*mcp.ListToolsResult, *mcpclient.Client)

WaitForExpectedToolsWithAuth creates authenticated MCP sessions with retry until the validateTools function returns nil (all expected tools are present). Returns the final tool list. This variant accepts StreamableHTTPCOptions for authenticated clients. The returned *mcpclient.Client is still open and must be closed by the caller so that subsequent tool calls can reuse the same session.

func WaitForPodDeletion added in v0.6.13 

func WaitForPodDeletion(ctx context.Context, c client.Client, name, namespace string, timeout, pollingInterval time.Duration)

WaitForPodDeletion waits for a pod to be fully deleted from the cluster. This is useful in AfterAll cleanup to ensure pods are gone before tests repeat.

func WaitForPodsReady 

func WaitForPodsReady(
	ctx context.Context,
	c client.Client,
	namespace string,
	labels map[string]string,
	timeout time.Duration,
	pollingInterval time.Duration,
)

WaitForPodsReady waits for at least one pod matching labels to be ready. This is used when waiting for a single expected pod to be ready (e.g., one replica deployment).

func WaitForVirtualMCPServerReady 

func WaitForVirtualMCPServerReady(
	ctx context.Context,
	c client.Client,
	name, namespace string,
	timeout time.Duration,
	pollingInterval time.Duration,
)

WaitForVirtualMCPServerReady waits for a VirtualMCPServer to reach Ready status and ensures at least one associated pod is actually running and ready. This is used when waiting for a single expected pod (e.g., one replica deployment).

func WithHttpLoggerOption added in v0.6.13 

func WithHttpLoggerOption() transport.StreamableHTTPCOption

WithHttpLoggerOption returns a transport.StreamableHTTPCOption that logs to GinkgoLogr. This is useful for debugging HTTP requests and responses.

Types

type BackendConfig added in v0.6.13 

type BackendConfig struct {
	Name                  string
	Namespace             string
	GroupRef              string
	Image                 string
	Transport             string // defaults to "streamable-http" if empty
	ExternalAuthConfigRef *mcpv1alpha1.ExternalAuthConfigRef
	Secrets               []mcpv1alpha1.SecretRef
	Env                   []mcpv1alpha1.EnvVar // additional env vars beyond TRANSPORT
	// Resources overrides the default resource requests/limits. When nil,
	// defaultMCPServerResources() is used to ensure containers are scheduled
	// with reasonable resource guarantees and do not compete excessively.
	Resources *mcpv1alpha1.ResourceRequirements
}

BackendConfig holds configuration for creating a backend MCPServer in tests.

type InitializedMCPClient added in v0.6.9 

type InitializedMCPClient struct {
	Client *mcpclient.Client
	Ctx    context.Context
	Cancel context.CancelFunc
}

InitializedMCPClient holds an initialized MCP client with its associated context

func CreateInitializedMCPClient added in v0.6.9 

func CreateInitializedMCPClient(nodePort int32, clientName string, timeout time.Duration) (*InitializedMCPClient, error)

CreateInitializedMCPClient creates an MCP client, starts the transport, and initializes the connection with the given client name. Returns an InitializedMCPClient that should be closed when done using defer client.Close().

func (*InitializedMCPClient) Close added in v0.6.9 

func (c *InitializedMCPClient) Close()

Close cleans up the MCP client resources

type MockHTTPServerInfo added in v0.6.14 

type MockHTTPServerInfo struct {
	Name      string
	Namespace string
	URL       string // In-cluster URL: http://<name>.<namespace>.svc.cluster.local
}

MockHTTPServerInfo contains information about a deployed mock HTTP server

func CreateMockHTTPServer added in v0.6.14 

func CreateMockHTTPServer(
	ctx context.Context,
	c client.Client,
	name, namespace string,
	timeout, pollingInterval time.Duration,
) *MockHTTPServerInfo

CreateMockHTTPServer creates an in-cluster mock HTTP server for testing fetch tools. This avoids network issues with external URLs like https://example.com in CI.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.