GitLab Well Architected
Cookbook navigation

Example: spot a response change that passing tests miss

An MR renames a shipment response field from status to state. Its updated unit test passes. Before merging, you want to know whether that says anything about the clients still using the old response.

Share the change and a caller

Paste this diff into the original prompt:

 def shipment_response():
-    return {"id": "shp_123", "status": "in_transit"}
+    return {"id": "shp_123", "state": "in_transit"}

 def test_shipment_response():
-    assert shipment_response()["status"] == "in_transit"
+    assert shipment_response()["state"] == "in_transit"

Then add the client that hasn't changed:

def tracking_label(shipment):
    """Read a shipment response and return the status for display.

    Expects a mapping with a status key. Has no side effects and raises KeyError
    when that key is missing, as it is in the proposed response.
    """
    return shipment["status"]

Look beyond the updated test

Duo should explain how renaming the response field affects callers that read status. Although the function still takes no arguments and returns a dictionary, the caller depends on a key that the new response omits.

The new unit test only shows that the producer returns state. Calling tracking_label with that response raises KeyError: 'status'. A test that includes the caller would expose the problem the producer-only test misses.

Discuss how the change could be introduced

Try this follow-up:

Some clients are deployed independently. What could we do to introduce state
without immediately breaking clients that still read status? What would we need
to know before removing the old field?

One option is to return both fields while clients move to the new name. You'd need to keep both values consistent and check whether clients accept an additional field. A versioned endpoint might fit better if the response must change incompatibly.

Use the conversation to identify which callers and transition options need checking. A passing producer test leaves client compatibility unresolved, and a proposed transition still needs testing with those clients. Supplying a representative caller in your own MR gives you a concrete place to start.

Back to the prompt