Make the matcher classes private and write convenience functions to r…

…educe boilerplate.

test/integrationtests/voight_kampff/__init__.py

@@ -16,14 +16,14 @@
 from .tools import (
     emit_utterance,
     format_dialog_match_error,
+    match_dialog,
+    match_message,
+    match_message_criteria,
     mycroft_responses,
     print_mycroft_responses,
     then_wait,
     then_wait_fail,
     wait_for_audio_service,
     wait_for_dialog,
     wait_for_dialog_match,
-    VoightKampffCriteriaMatcher,
-    VoightKampffDialogMatcher,
-    VoightKampffEventMatcher
 )

test/integrationtests/voight_kampff/tools.py

@@ -24,7 +24,7 @@
 DEFAULT_TIMEOUT = 10
 
 
-class VoightKampffEventMatcher:
+class _VoightKampffMessageMatcher:
     """Matches a specified message type to messages emitted on the bus.
 
     Attributes:
@@ -88,7 +88,7 @@ def _build_error_message(self):
         )
 
 
-class VoightKampffDialogMatcher(VoightKampffEventMatcher):
+class _VoightKampffDialogMatcher(_VoightKampffMessageMatcher):
     """Variation of VoightKampffEventMatcher for matching dialogs.
 
     Attributes:
@@ -135,7 +135,7 @@ def _build_error_message(self):
             self.error_message += "\tMycroft didn't respond"
 
 
-class VoightKampffCriteriaMatcher(VoightKampffEventMatcher):
+class _VoightKampffCriteriaMatcher(_VoightKampffMessageMatcher):
     """Variation of VoightKampffEventMatcher for matching event data.
 
     In some cases, matching the message type is not enough.  The test
@@ -171,6 +171,67 @@ def _build_error_message(self):
         pass
 
 
+def match_message(context: Any, message_type: str,
+                  timeout: int = None) -> Tuple[bool, str]:
+    """Attempts to match emitted bus messages to the specified message type.
+
+    Args:
+        context: behave context
+        message_type: message type that will satisfy the match condition.
+        timeout: overrides the default timeout to wait for a match condition
+
+    Returns:
+        Whether or not a match was found and an error message.  Error message
+        will be empty if match was found.
+    """
+    message_matcher = _VoightKampffMessageMatcher(context, message_type)
+    message_matcher.match(timeout)
+
+    return message_matcher.match_found, message_matcher.error_message
+
+
+def match_dialog(context: Any, dialogs: List[str],
+                 timeout: int = None) -> Tuple[bool, str]:
+    """Attempts to match emitted "speak" messages to one or more dialogs.
+
+    Args:
+        context: behave context
+        dialogs: list of dialog files that will satisfy the match condition
+        timeout: overrides the default timeout to wait for a match condition
+
+    Returns:
+        Whether or not a match was found and an error message.  Error message
+        will be empty if match was found.
+    """
+    dialog_matcher = _VoightKampffDialogMatcher(context, dialogs)
+    dialog_matcher.match(timeout)
+
+    return dialog_matcher.match_found, dialog_matcher.error_message
+
+
+def match_message_criteria(context: Any, message_type: str,
+                           criteria_matcher: Callable,
+                           timeout: int = None) -> Tuple[bool, str]:
+    """Attempts to match emitted bus messages to the specified message type.
+
+    Args:
+        context: behave context
+        message_type: message type that will satisfy the match condition.
+        criteria_matcher: function that will be used to interrogate the
+            message data for a match condition
+        timeout: overrides the default timeout to wait for a match condition
+
+    Returns:
+        Whether or not a match was found and an error message.  Error message
+        will be empty if match was found.
+    """
+    criteria_matcher = _VoightKampffCriteriaMatcher(context, message_type,
+                                                    criteria_matcher)
+    criteria_matcher.match(timeout)
+
+    return criteria_matcher.match_found, criteria_matcher.error_message
+
+
 # TODO: Remove in 21.08
 class CriteriaWaiter:
     """Wait for a message to meet a certain criteria.
@@ -305,10 +366,7 @@ def then_wait(msg_type: str, criteria_func: Callable, context: Any,
     Returns:
         The success of the match attempt and an error message.
     """
-    matcher = VoightKampffCriteriaMatcher(msg_type, context, criteria_func)
-    matcher.match(timeout)
-
-    return matcher.match_found, matcher.error_message
+    return match_message_criteria(context, msg_type, criteria_func, timeout)
 
 
 def then_wait_fail(msg_type: str, criteria_func: Callable, context: Any,
@@ -475,7 +533,7 @@ def wait_for_audio_service(context: Any, message_type: str):
         AssertionError if no match is found.
     """
     msg_type = 'mycroft.audio.service.{}'.format(message_type)
-    event_matcher = VoightKampffEventMatcher(msg_type, context)
+    event_matcher = _VoightKampffMessageMatcher(msg_type, context)
     event_matcher.match()
 
     assert event_matcher.match_found, event_matcher.error_message