More debuggable UsageExpectation (bugfix)

[Hook25]

Description

Currently when we receive a UsageExpectation error in an issue it is really hard to know what went wrong. The reason is that the usage expectations are modified by any function but there is no way to know how we got to a given set. This PR starts tracking the modifications and includes them in the exception. Additionally the error now is clear about it being an error in Checkbox (the old error was weird for our users) and to report it to us.

On the implementation side, the old implementation compared the function code and had to jump through a few hoops to get the actual calling function and its code (given that it could have been decorated). This new implemtation removes all that and just uses the function name. This makes:

• The code way easier to read
• The code faster (no inspect, no f_code comparison, no frozenset etc. with way less pointless debug logging)
• No difference in my opinion, UA are scoped to the instance, if the function name matches it is the same function (*)

(*) Technically false, it may be a different function if the bound function was changed at runtime, but I don't see a legitimate reason to do that, especially in the SessionAssistant

Resolved issues

N/A

Documentation

N/A

Tests

To test this remove some UsageExpectation from (for example) _get_allowed_calls_in_normal_state. You will see the new error with a history of modifications.

Here is a sample of the new error:

Uh, oh...

If you see this message then there is a bug somewhere in Checkbox. We are
sorry for this. Please report this to us.

You are not expected to call SessionAssistant.get_job at this time.
The set of allowed calls, at this time, is:

 - call SessionAssistant.get_job_state() to to access the state of any job.
 - call SessionAssistant.export_to_transport() to to export the results and send them.
 - call SessionAssistant.export_to_file() to to export the results to a file.
 - call SessionAssistant.export_to_stream() to to export the results to a stream.
 - call SessionAssistant.finalize_session() to to mark the session as complete.
 - call SessionAssistant.get_session_id() to to get the id of currently running session.
 - call SessionAssistant.finish_bootstrap() to to finish bootstrapping.

The last 5 modifications were done by (most recent last):

 - SessionAssistant.use_alternate_configuration
 - SessionAssistant.select_test_plan
 - SessionAssistant.start_bootstrap
 - SessionAssistant.finish_bootstrap
 - SessionAssistant.prepare_resume_session

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.97%. Comparing base (d003f02) to head (cb8e81e).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
checkbox-ng/plainbox/impl/session/assistant.py	51.42%	16 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2728      +/-   ##
==========================================
- Coverage   60.03%   59.97%   -0.06%     
==========================================
  Files         487      487              
  Lines       48935    48969      +34     
  Branches     8765     8764       -1     
==========================================
- Hits        29377    29369       -8     
- Misses      18636    18682      +46     
+ Partials      922      918       -4     

Flag	Coverage Δ
checkbox-ng	76.16% <73.52%> (-0.16%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR improves the debuggability of UsageExpectation failures by tracking and displaying a short history of which methods most recently modified the allowed-call set, and updates SessionAssistant to use the new API for modifying/enforcing expectations.

Changes:

• Refactors UsageExpectation to store allowed calls by function name and adds modification-history tracking that is included in UnexpectedMethodCall messages.
• Updates SessionAssistant to call enforce(self.<method>) and to mutate expectations via allow(), disallow(), and allow_all().
• Updates developer tests to reflect the new exception messaging; removes a SessionAssistant test that previously asserted allowed-call transitions.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
checkbox-ng/plainbox/impl/developer.py	Refactors UsageExpectation enforcement/modification logic and enhances UnexpectedMethodCall messages with modification history.
checkbox-ng/plainbox/impl/session/assistant.py	Migrates SessionAssistant’s usage-expectation enforcement and allowed-call transitions to the new API.
checkbox-ng/plainbox/impl/test_developer.py	Updates unit tests to use the new enforcement API and to validate the updated error message format.
checkbox-ng/plainbox/impl/session/test_assistant.py	Removes the expected-call-sequence test that depended on the previous allowed_calls structure.

Comments suppressed due to low confidence (1)

checkbox-ng/plainbox/impl/session/test_assistant.py:76

• test_expected_call_sequence was removed, which eliminates the only coverage in this module for SessionAssistant's expected-call state transitions. Given the refactor to UsageExpectation.allow/allow_all/disallow, it would be better to update the test to assert the new behavior (e.g., calling a method that should now be disallowed raises UnexpectedMethodCall and the message/history are sensible).

    def _get_mock_providers(self):
        """Get some mocked provides for testing."""
        return [self.p1, self.p2, self.p3]

    @mock.patch(
        "plainbox.impl.session.assistant.UsageExpectation",
        new=mock.MagicMock(),
    )
    @mock.patch("plainbox.impl.session.assistant._logger")

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[fernando79513]

Overall, great improvement, It took me a while to undestand it, but I can get it now, before it was too cryptic, XD

I have added a couple of comments, so we can maybe clarify it even more.

[fernando79513]

LGTM +1!