Testing ensures your compositions and control planes work as expected, follow best practices, and meet your organizations requirements. You can run your projects in a development control plane and author tests to verify specific capabilities in your project.
Prerequisites
To test your compositions and run end-to-end tests, make sure you have:
- The
upCLIv0.38or higher installed - An Upbound account
Development control planes
Development control planes are lightweight, temporary environments in Upbound for testing your control plane projects. They provide simplified infrastructure with limited resources and a 24-hour lifespan. Development control planes allow you to test APIs and compositions without the cost or complexity of production environments.
Render your composition
Preview how your composition creates resources with the up composition render
command before you deploy to a development control plane.
up composition render apis/xbuckets/composition.yaml examples/bucket/example-xr.yaml
This command requires a Composite Resource (XR) file that defines the resources you want to create. The XR file contains the same parameters as your example claim but explicitly defines the API type and target cluster.
Rendering locally validates your build, configuration and resource orchestration render as expected before you deploy to a development control plane.
Run your development control plane
To run your control plane projects on a development control plane, use the up project run command.
up project run
The up project run command creates a development control plane in your Upbound
Cloud organization. The development control plane creates your project’s custom
resources, compositions and functions in a limited scope isolated control plane.
You can validate your results in the Upbound Console and make changes to ensure your project operates as expected before you move to production.
Upbound limits the number of concurrent development control planes you can create based on your account tier. Review Upbound’s pricing for more information.
Test your project locally
You can also generate tests for your compositions locally with the up test generate command.
Generate a composition test
Composition tests validate the logic of your compositions without requiring a live environment. They simulate the composition controller’s behavior, allowing you to test resource creation, dependencies, and state transitions with mock data.
Composition tests validate composition logic without required a live environment. They simulate the composition controller’s behavior, letting you test resource creation, dependencies, and state transitions with mock data.
You can generate test with up test generate for composition tests.
You can write tests in KCL or Python.
For example, to generate a composition test:
up test generate <name> --language=python
Author a composition test
Composition tests use a declarative API in KCL or Python. Each test models a single composition controller loop, making testing more streamlined for reading and debugging.
This testing command simulates the Crossplane composition controller. The controller evaluates the current state of resources, processes the composition, and makes necessary changes. The command recreates this process locally to verify composition logic.
from .model.io.upbound.dev.meta.compositiontest import v1alpha1 as compositiontest
from .model.io.k8s.apimachinery.pkg.apis.meta import v1 as k8s
test = compositiontest.CompositionTest(
metadata=k8s.ObjectMeta(
name="test-xstoragebucket-default-python",
),
spec = compositiontest.Spec(
assertResources=[],
compositionPath="apis/xstoragebuckets/composition.yaml",
xrPath="examples/xstoragebuckets/example.yaml",
xrdPath="apis/xstoragebuckets/definition.yaml",
timeoutSeconds=120,
validate=False,
)
)
Run a composition test
You can run your composition tests using the up test run command.
To run all tests, define the path and * to include
everything in that directory.
up test run tests/*
To run a specific test, give the full path of that test:
up test run tests/xstoragebucket-default/main.k
You can provide wildcards to run tests matching a pattern:
up test run tests/xstoragebucket/**/*.k
The command returns a summary of results:
up test run tests/*
...
SUCCESS
SUCCESS Tests Summary:
SUCCESS ------------------
SUCCESS Total Tests Executed: 4
SUCCESS Passed tests: 4
SUCCESS Failed tests: 0
When you run Compositions tests, Upbound:
- Detects the test language and converts to a unified format.
- Builds and pushes the project to local daemon.
- Sets the context to the new control plane.
- Executes tests and validates results.
Generate an end-to-end test
End-to-end tests validate compositions in real environments, ensuring creation, deletion, and operations work as expected.
You can generate test with up test generate for end-to-end tests.
You can write tests in KCL or Python.
For example, to generate a end-to-end test:
up test generate <name> --e2e --language=python
Author an end-to-end test
End-to-end tests use the E2ETest API, written in KCL or Python.
from .model.io.upbound.dev.meta.e2etest import v1alpha1 as e2etest
from .model.io.k8s.apimachinery.pkg.apis.meta import v1 as k8s
from .model.com.example.platform.xstoragebucket import v1alpha1 as xstoragebucket
from .model.io.upbound.aws.providerconfig import v1beta1 as providerconfig
bucket_manifest = xstoragebucket.XStorageBucket(
metadata=k8s.ObjectMeta(
name="uptest-bucket-xr",
),
spec=xstoragebucket.Spec(
parameters=xstoragebucket.Parameters(
acl="private",
region="eu-central-1",
versioning=True,
),
),
)
provider_config = providerconfig.ProviderConfig(
metadata=k8s.ObjectMeta(
name="default",
),
spec=providerconfig.Spec(
credentials=providerconfig.Credentials(
source="Upbound",
upbound=providerconfig.Upbound(
webIdentity=providerconfig.WebIdentity(
roleARN="arn:aws:iam::609897127049:role/example-project-aws-uptest",
),
),
),
),
)
test = e2etest.E2ETest(
metadata=k8s.ObjectMeta(
name="e2etest-xstoragebucket-python",
),
spec=e2etest.Spec(
crossplane=e2etest.Crossplane(
autoUpgrade=e2etest.AutoUpgrade(
channel=e2etest.Channel.Rapid,
),
),
defaultConditions=[
"Ready",
],
manifests=[bucket_manifest.model_dump()],
extraResources=[provider_config.model_dump()],
skipDelete=False,
timeoutSeconds=4500,
)
)
Run an end-to-end test
You can run your end-to-end tests using the up test run command.
To run all tests, define the path and * to include
everything in that directory.
up test run --e2e tests/*
To run a specific test, give the full path of that test:
up test run --e2e tests/e2etest-xstoragebucket-default/main.k
You can provide wildcards to run tests matching a pattern:
up test run --e2e tests/xstoragebucket/**/*.k
The command returns a summary of results:
up test run --e2e tests/*
...
SUCCESS
SUCCESS Tests Summary:
SUCCESS ------------------
SUCCESS Total Tests Executed: 4
SUCCESS Passed tests: 4
SUCCESS Failed tests: 0
When you run E2E tests, Upbound:
- Detects the test language and converts to a unified format.
- Builds and pushes the project.
- Creates a development control plane with the specified Crossplane version.
- Sets the context to the new control plane.
- Applies extra resources in order and waits for their conditions.
- Executes tests and validates results.
- Exports resources for debugging on failure.
- Cleans up the control plane when tests complete or the TTL expires.
Complex testing scenarios
For compositions requiring multiple controller loops (with one resource depending on another, for example), create separate tests for each stage.
Mock states help test scenarios like:
- Resources that already exist.
- How your composition handles different resource states.
- Conditional dependency chains between resources.
Next steps
Now that you know how to write tests for your control plane projects, the next guide shows you how to build and push your projects.
