In this guide we will go through how to write Scenario tests for a charm library we are developing:
<charm root>/lib/charms/my_charm/v0/my_lib.py
The intended behaviour of this library (requirer side) is to copy data from the provider app databags and collate it in the own application databag. The requirer side library does not interact with any lifecycle event; it only listens to relation events.
Setup
Assuming you have a library file already set up and ready to go (see charmcraft create-lib otherwise), you now need to
pip install ops-scenario and create a test file in <charm root>/tests/scenario/test_my_lib.py
Base test
# `<charm root>/tests/scenario/test_my_lib.py`
import pytest
import ops
from scenario import Context, State
from lib.charms.my_Charm.v0.my_lib import MyObject
class MyTestCharm(ops.CharmBase):
META = {
"name": "my-charm"
}
def __init__(self, framework):
super().__init__(framework)
self.obj = MyObject(self)
framework.observe(self.on.start, self._on_start)
def _on_start(self, _):
pass
@pytest.fixture
def context():
return Context(MyTestCharm, meta=MyTestCharm.META)
@pytest.mark.parametrize('event', (
'start', 'install', 'stop', 'remove', 'update-status', #...
))
def test_charm_runs(context, event):
"""Verify that MyObject can initialize and process any event except relation events."""
# arrange
state_in = State()
# act
context.run(event, state_in)
Simple use cases
Relation endpoint wrapper lib
If MyObject is a relation endpoint wrapper such as traefik's ingress-per-unit lib,
a frequent pattern is to allow customizing the name of the endpoint that the object is wrapping. We can write a scenario test like so:
# `<charm root>/tests/scenario/test_my_lib.py`
import pytest
import ops
from scenario import Context, State, Relation
from lib.charms.my_Charm.v0.my_lib import MyObject
@pytest.fixture(params=["foo", "bar"])
def endpoint(request):
return request.param
@pytest.fixture
def my_charm_type(endpoint):
class MyTestCharm(ops.CharmBase):
META = {
"name": "my-charm",
"requires":
{endpoint: {"interface": "my_interface"}}
}
def __init__(self, framework):
super().__init__(framework)
self.obj = MyObject(self, endpoint=endpoint)
framework.observe(self.on.start, self._on_start)
def _on_start(self, _):
pass
return MyTestCharm
@pytest.fixture
def context(my_charm_type):
return Context(my_charm_type, meta=my_charm_type.META)
def test_charm_runs(context):
"""Verify that the charm executes regardless of how we name the requirer endpoint."""
# arrange
state_in = State()
# act
context.run('start', state_in)
@pytest.mark.parametrize('n_relations', (1, 2, 7))
def test_charm_runs_with_relations(context, endpoint, n_relations):
"""Verify that the charm executes when there are one or more relations on the endpoint."""
# arrange
state_in = State(relations=[
Relation(endpoint=endpoint, interface='my-interface', remote_app_name=f"remote_{n}") for n in range(n_relations)
])
# act
state_out = context.run('start', state_in)
# assert
for relation in state_out.relations:
assert not relation.local_app_data # remote side didn't publish any data.
@pytest.mark.parametrize('n_relations', (1, 2, 7))
def test_relation_changed_behaviour(context, endpoint, n_relations):
"""Verify that the charm lib does what it should on relation changed."""
# arrange
relations = [Relation(
endpoint=endpoint, interface='my-interface', remote_app_name=f"remote_{n}",
remote_app_data={"foo": f"my-data-{n}"}
) for n in range(n_relations)]
state_in = State(relations=relations)
# act
state_out: State = context.run(relations[0].changed_event, state_in)
# assert
for relation in state_out.relations:
assert relation.local_app_data == {"collation": ';'.join(f"my-data-{n}" for n in range(n_relations))}
Advanced use cases
Testing internal (charm-facing) library APIs
Suppose that MyObject has a data method that exposes to the charm a list containing the remote databag contents (the my-data-N we have seen above).
We can use scenario.Context.manager to run code within the lifetime of the Context like so:
import pytest
import ops
from scenario import Context, State, Relation
from lib.charms.my_Charm.v0.my_lib import MyObject
@pytest.mark.parametrize('n_relations', (1, 2, 7))
def test_my_object_data(context, endpoint, n_relations):
"""Verify that the charm lib does what it should on relation changed."""
# arrange
relations = [Relation(
endpoint=endpoint, interface='my-interface', remote_app_name=f"remote_{n}",
remote_app_data={"foo": f"my-data-{n}"}
) for n in range(n_relations)]
state_in = State(relations=relations)
with context.manager(relations[0].changed_event, state_in) as mgr:
# act
state_out = mgr.run() # this will emit the event on the charm
# control is handed back to us before ops is torn down
# assert
charm = mgr.charm # the MyTestCharm instance ops is working with
obj: MyObject = charm.obj
assert obj.data == [
f"my-data-{n}" for n in range(n_relations)
]