Google Git
Sign in
chromium / chromiumos / third_party / virtual-usb-printer / f2f199db501ab5a0c68a7b0be18a3a228d187f26 / . / mock_printer
tree: b3a9b23d6e2ae4b052bf7a12c18a326dfdfb4fc1 [path history] [tgz]
  1. doc/
  2. proto/
  3. argument_variants.cc
  4. argument_variants.h
  5. BUILD.gn
  6. cardinality_helper.cc
  7. cardinality_helper.h
  8. cardinality_helper_test.cc
  9. ipp_matching.cc
  10. ipp_matching.h
  11. ipp_matching_test.cc
  12. ipp_matching_validation.cc
  13. ipp_matching_validation.h
  14. ipp_matching_validation_test.cc
  15. libipp_helper.cc
  16. libipp_helper.h
  17. libipp_helper_test.cc
  18. mock_printer.cc
  19. mock_printer.h
  20. parse_textproto.cc
  21. parse_textproto.h
  22. proto_to_http.cc
  23. proto_to_http.h
  24. proto_to_http_test.cc
  25. proto_to_libipp.cc
  26. proto_to_libipp.h
  27. proto_to_libipp_test.cc
  28. README.md
  29. test_case_holder.cc
  30. test_case_holder.h
  31. wrapped_matcher.cc
  32. wrapped_matcher.h
  33. wrapped_test_case_step.cc
  34. wrapped_test_case_step.h
  35. wrapped_test_case_step_test.cc
mock_printer/README.md

Mock Printer Mode

Test cases in mock printer mode are built from control flow Protobufs. The appendices in this documentation provide some examples of their mechanics.

Much of this document intermingles usage and maintenance notes. Casual users need not read this document in detail: try reading an existing test first and following it by example. Return to this document if you seek greater depth.

TODO(b/178649877): document the command-line flag that will cause virtual-usb-printer to enter mock printer mode.
TODO(b/178649877): document the general usage of mock printer mode.

Terminology

  • Test case - a series of steps that verify at least (and hopefully at most) one particular behavior of the Chromium OS printing stack.
  • Test case step - a cluster of expectations and at most one response. In prose, “virtual-usb-printer expects some of events A, B, and C; when the expectation is met, virtual-usb-printer responds with response D.”
  • Matcher - an expression that defines how an expectation is met. For example, “Expectation X is met when virtual-usb-printer receives message with contents A, B, and C.”
Mock printer mode will only support building matchers for IPP messages in the near term.

Test case steps (TestCaseSteps) have some additional associated terms:

  • Progression - a test case step makes progress when virtual-usb-printer receives a message that matches some expectation of said step. virtual-usb-printer marks the particular expectation as met, thereby progressing the test case step.
  • Fulfillment - a test case step is fulfilled when virtual-usb-printer has received enough messages s.t. said step could be considered complete.
  • Saturation - a test case step is saturated when virtual-usb-printer cannot match any more expectations against it without exceeding the specified Cardinality::Count; the test case step is forbidden from progressing further.
  • Reachable - a test case step is reachable when it is eligible for progression. For example, the “current” test case step is always trivially reachable.
Fulfillment and saturation are always synonymous when the test case step has Cardinality::Type::{ALL_IN_ORDER,ALL_IN_ANY_ORDER}: all given expectations must be met, fulfilling and saturating the step simultaneously. They can diverge for Cardinality::Type::{SOME_OF,REPEATED}, depending on the associated Cardinality::Count.

Source Code Layout

  • proto/ - defines Protobuf representations of test cases: control flow, matchers, and responses.
  • ipp_matching_validation.h - used to verify that the IPP message Protobufs used as matchers are well-formed.
  • ipp_matching.h - used to match mocking::IppMessage Protobufs with incoming ipp::Request messages (received by libipp).
  • parse_textproto.h - declares functions for parsing the Protobufs defined in the proto/ subdirectory.
  • test_case_holder.h - defines the container in which virtual-usb-printer holds given test cases. See the diagram below.
    • cardinality_helper.h - defines an abstract class that allows callers to progress control flow.
    • wrapped_matcher.h - defines a mock-friendly way to call matcher functions for test case steps.

TestCaseHolder Layout

The TestCaseHolder is the top-level container for mocking::TestCases.

TestCaseHolder members

  • The TestCaseHolder tracks the overall progression of the TestCase, including what TestCaseSteps are reachable.
  • The WrappedTestCaseStep tracks the progression of a single mocking::TestCaseStep, including which mocking::ExpectationWithResponses have been fulfilled.
    • WrappedTestCaseStep contains a WrappedMatcher, which is an injection-friendly wrapper for matching functions (like those in ipp_matching.h).

Appendices

  • TestCase Flow - describes how virtual-usb-printer progresses through a given mocking::TestCase.
  • TestCaseStep With Multiple Expectations - details some minutiae on how virtual-usb-printer reasons through individual mocking::TestCaseSteps when more than one mocking::ExpectationWithResponse is given.