Write integration tests for your charm

From Zero to Hero: Write your first Kubernetes charm > Write integration tests for your charm

See previous: Write scenario tests for your charm

This document is part of a series, and we recommend you follow it in sequence. However, you can also jump straight in by checking out the code from the previous branches:

git clone https://github.com/canonical/juju-sdk-tutorial-k8s.git
cd juju-sdk-tutorial-k8s
git checkout 09_scenario_test
git checkout -b 10_integration_testing

A charm should function correctly not just in a mocked environment but also in a real deployment.

For example, it should be able to pack, deploy, and integrate without throwing exceptions or getting stuck in a waiting or a blocked status – that is, it should correctly reach a status of active or idle.

You can ensure this by writing integration tests for your charm. In the charming world, these are usually written with the pytest-operator library.

In this chapter you will write two small integration tests – one to check that the charm packs and deploys correctly and one to check that the charm integrates successfully with the PostgreSQL database.

Contents:

  1. Prepare your test environment
  2. Prepare your test directory
  3. Write and run a pack-and-deploy integration test
  4. Write and run an integrate-with-database integration test
  5. Review the final code

Prepare your test environment

In your tox.ini file, add the following new environment:

[testenv:integration]
description = Run integration tests
deps =
    pytest
    juju
    pytest-operator
    -r {tox_root}/requirements.txt
commands =
    pytest -v \
           -s \
           --tb native \
           --log-cli-level=INFO \
           {posargs} \
           {[vars]tests_path}/integration

Prepare your test directory

Create a tests/integration directory:

mkdir ~/fastapi-demo/tests/integration

Write and run a pack-and-deploy integration test

Let’s begin with the simplest possible integration test, a smoke test. This test will build and deploy the charm and verify that the installation hooks finish without any error.

In your tests/integration directory, create a file test_charm.py and add the following test case:

import asyncio
import logging
from pathlib import Path

import pytest
import yaml
from pytest_operator.plugin import OpsTest

logger = logging.getLogger(__name__)

METADATA = yaml.safe_load(Path("./charmcraft.yaml").read_text())
APP_NAME = METADATA["name"]


@pytest.mark.abort_on_fail
async def test_build_and_deploy(ops_test: OpsTest):
    """Build the charm-under-test and deploy it.

    Assert on the unit status before any relations/configurations take place.
    """
    # Build and deploy charm from local source folder
    charm = await ops_test.build_charm(".")
    resources = {
        "demo-server-image": METADATA["resources"]["demo-server-image"][
            "upstream-source"
        ]
    }

    # Deploy the charm and wait for blocked/idle status
    # The app will not be in active status as this requires a database relation
    await asyncio.gather(
        ops_test.model.deploy(charm, resources=resources, application_name=APP_NAME),
        ops_test.model.wait_for_idle(
            apps=[APP_NAME], status="blocked", raise_on_blocked=False, timeout=120
        ),
    )

In your Multipass Ubuntu VM, run the test:

tox -e integration

The test takes some time to run as the pytest-operator running in the background will add a new model to an existing cluster (whose presence it assumes). If successful, it’ll verify that your charm can pack and deploy as expected.

Write and run an integrate-with-database integration test

The charm requires a database to be functional. Let’s verify that this behaviour works as intended. For that, we need to deploy a database to the test cluster and integrate both applications. Finally, we should check that the charm reports an active status.

In your tests/integration/test_charm.py file add the following test case:

@pytest.mark.abort_on_fail
async def test_database_integration(ops_test: OpsTest):
    """Verify that the charm integrates with the database.

    Assert that the charm is active if the integration is established.
    """
    await ops_test.model.deploy(
        application_name="postgresql-k8s",
        entity_url="postgresql-k8s",
        channel="14/stable",
    )
    await ops_test.model.integrate(f"{APP_NAME}", "postgresql-k8s")
    await ops_test.model.wait_for_idle(
        apps=[APP_NAME], status="active", raise_on_blocked=False, timeout=120
    )

But if you run the one and then the other (as separate pytest ... invocations, then two separate models will be created unless you pass --model=some-existing-model to inform pytest-operator to use a model you provide.

In your Multipass Ubuntu VM, run the test again:

ubuntu@charm-dev:~/fastapi-demo$ tox -e integration

The test may again take some time to run.

Pro tip: To make things faster, use the --model=<existing model name> to inform pytest-operator to use the model it has created for the first test. Otherwise, charmers often have a way to cache their pack or deploy results; an example is https://github.com/canonical/spellbook .

When it’s done, the output should show two passing tests:

...
  demo-api-charm/0 [idle] waiting: Waiting for database relation
INFO     juju.model:model.py:2759 Waiting for model:
  demo-api-charm/0 [idle] active: 
PASSED
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- live log teardown --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
INFO     pytest_operator.plugin:plugin.py:783 Model status:

Model            Controller       Cloud/Region        Version  SLA          Timestamp
test-charm-2ara  main-controller  microk8s/localhost  3.1.5    unsupported  09:45:56+02:00

App             Version  Status  Scale  Charm           Channel    Rev  Address        Exposed  Message
demo-api-charm  1.0.1    active      1  demo-api-charm               0  10.152.183.99  no       
postgresql-k8s  14.7     active      1  postgresql-k8s  14/stable   73  10.152.183.50  no       

Unit               Workload  Agent  Address       Ports  Message
demo-api-charm/0*  active    idle   10.1.208.77          
postgresql-k8s/0*  active    idle   10.1.208.107         

INFO     pytest_operator.plugin:plugin.py:789 Juju error logs:


INFO     pytest_operator.plugin:plugin.py:877 Resetting model test-charm-2ara...
INFO     pytest_operator.plugin:plugin.py:866    Destroying applications demo-api-charm
INFO     pytest_operator.plugin:plugin.py:866    Destroying applications postgresql-k8s
INFO     pytest_operator.plugin:plugin.py:882 Not waiting on reset to complete.
INFO     pytest_operator.plugin:plugin.py:855 Forgetting main...


========================================================================================================================================================================== 2 passed in 290.23s (0:04:50) ==========================================================================================================================================================================
  integration: OK (291.01=setup[0.04]+cmd[290.97] seconds)
  congratulations :) (291.05 seconds)

Congratulations, with this integration test you have verified that your charms relation to PostgreSQL works as well!

Review the final code

For the full code see: 10_integration_testing

For a comparative view of the code before and after this doc see: Comparison

See next: Open a Kubernetes port in your charm

Contributors: @bschimke95, @mylesjp, @tony-meyer, @tmihoc

Last updated 27 days ago. Help improve this document in the forum.