Package: questions-three
Questions ThreeA Library for Serious Software Interrogators (and silly ones too)Stop! Who would cross the Bridge of Death must answer me these questions three, ere the other side he see.-- The KeeperWhy you want thisThe vast majority of support for automatedsoftware checkingfalls into two main groups: low-level unit checking tools that guide design and maintain control over code as it is being written, andhigh-level system checkingtools that reduce the workload of human testers after the units have been integrated.The first group is optimized for precision and speed.  A good unit check proves exactly one point in milliseconds.  The second group is optimized for efficient use of human resources, enabling testers to repeat tedious actions without demanding much (or any) coding effort.Engineering is all about trade-offs.  We can reduce the coding effort, but only if we are willing to sacrifice control.   This makes the existing high-level automation tools distinctly unsatisfactory to testers who would prefer the opposite trade: more control in exchange for the need to approach automation as abona-fidesoftware development project.If you want complete control over your system-level automation and are willing to get some coding dirt under your fingernails in exchange, then Questions Three could be your best friend.As a flexible library rather than an opinionated framework, it will support you without dictating structures or rules.  Its features were designed to work together, but you can use them separately or even integrate them into the third-party or homegrown framework of your choice.A note on heretical terminologyThe vast majority of software professionals refer to inspection work done by machines as "automated testing."  James Bach and Michael Bolton makea strong casethat this is a dangerous abuse of the word "testing" and suggest that we use "checking" instead when we talk about executing a procedure with a well-defined expected outcome.Questions Three tries to maintain neutrality in this debate.  Where practical, it lets you choose whether you want to say "test" or "check."  Internally, it uses "test" for consistency with third-party libraries.  As the public face of the project, this documentation falls on the "check" side.  It says "check suite" where most testers would say "test suite."Orientation ResourcesArticle:"Waiter, There's aDatabasein My Unit Test!"explains the differences between unit, integration, and system testing and the role for each.Video:"Industrial Strength Automation"presentation from STARWEST 2019 makes the cases for and against building a serious automation program.  It concludes with an extended discussion on the history, purpose, and design of Questions Three.What's in the BoxScaffoldsthat help you structure your checks.  Chose one from the library or use them as examples to build your own.Reportersthat provide results as expected by various readers.  Use as many or as few as you would like, or follow the design pattern and build your own.Event Brokerwhich allows components to work together without knowing about one another.  Need to integrate a new kind of reporter?  Simply contact the broker and subscribe to relevant events.  No need to touch anything else.HTTP Clientthat tracks its own activity and converts failures to meaningful artifacts for test reports.GraphQL Clientthat leverages the HTTP Client for an easy to use GraphQL interface.Logging Subsystemthat, among other things, allows you to control which modules log at which level via environment variables.Vanilla Functionsthat you might find useful for checking and are entirely self-contained.   Use as many or as few as you would like.Bulk Suite Runnerthat lets you run multiple suites in parallel and control their execution via environment variables.Optional PackagesAmazon Web Services IntegrationsSelenium Integrationsthat facilitate compatibility checking and make Selenium WebDriver a full citizen of Question-Three's event-driven world.Quick StartInstall questions-threepip install questions-threeWrite the suitefrom questions_three.scaffolds.check_script import check, check_suite

with check_suite('ExampleSuite'):

  with check('A passing check'):
      assert True, 'That was easy'Run the suiteNo special executors are required.  Just run the script:python example_suite.pyReview the resultsThe console output should look like this:2018-08-13 14:52:55,725 INFO from questions_three.reporters.event_logger.event_logger: Suite "ExampleSuite" started
2018-08-13 14:52:55,726 INFO from questions_three.reporters.event_logger.event_logger: Check "A passing check" started
2018-08-13 14:52:55,726 INFO from questions_three.reporters.event_logger.event_logger: Check "A passing check" ended
2018-08-13 14:52:55,729 INFO from questions_three.reporters.event_logger.event_logger: Suite "ExampleSuite" endedThere should also be a reports directory which contains a report:> ls reports
ExampleSuite.xml    jenkins_statusExampleSuite.xml is a report in theJUnit XMLformat that can be consumed by many report parsers, including Jenkins CI.  It gets produced by the junit_reporter module.jenkins_status is a plain text file that aggregates the results of all test suites from a batch into a single result which Jenkins can display.   It gets produced by the jenkins_build_status module.ScaffoldsScaffolds provide a basic structure for your checks.  Their most important function is to publish events as your checks start, end, and fail.The top-to-bottom script scaffoldfrom questions_three.scaffolds.check_script import check, check_suite

with check_suite('ExampleSuite'):

  with check('A passing check'):
      assert True, 'That was easy'

  with check('A failing check'):
      assert False, 'Oops'If you don't like saying "check," you can say "test" instead:from questions_three.scaffolds.test_script import test, test_suite

with test_suite('ExampleSuite'):

  with test('A passing check'):
      assert True, 'That was easy'

  with test('A failing check'):
      assert False, 'Oops'This code is an ordinary executable python script, so you can simply execute it normally.python example_suite.pyThe xUnit style scaffoldAs its name suggests, the xUnit scaffold implements the well-wornxUnit pattern.from questions_three.scaffolds.xunit import TestSuite, skip


class MyXunitSuite(TestSuite):

    def setup_suite(self):
        """
        Perform setup that affects all tests here
        Changes to "self" will affect all tests.
        """
        print('This runs once at the start of the suite')

    def teardown_suite(self):
        print('This runs once at the end of the suite')

    def setup(self):
        """
        Perform setup for each test here.
        Changes to "self" will affect the current test only.
        """
        print('This runs before each test')

    def teardown(self):
        print('This runs after each test')

    def test_that_passes(self):
        """
        The method name is xUnit magic.
        Methods named "test..." get treated as test cases.
        """
        print('This test passes')

    def test_that_fails(self):
        print('This test fails')
        assert False, 'I failed'

    def test_that_errs(self):
        print('This test errs')
        raise RuntimeError('I tried to think but nothing happened')

    def test_that_skips(self):
        print('This test skips')
        skip("Don't do that")The most important advantage of the xUnit scaffold over the script one is that it automatically repeats the same set-up and tear-down routines betweentest_...functions.  Its main disadvantage is that the suites aren't as beautiful to read.Thanks to some metaclass hocus-pocus which you're free to gawk at by looking at the source code, this too is an ordinary Python executable file:python my_xunit_suite.pyThe Test Table ScaffoldThe Test Table scaffold was designed to support two use cases:You would like to repeat the same procedure with different sets of arguments.You would like to execute the same procedure multiple times to measure performance.Example test table that varies argumentsfrom expects import expect, equal
from questions_three.scaffolds.test_table import execute_test_table

TABLE = (
    ('x', 'y', 'expect sum', 'expect exception'),
    (2, 2, 4, None),
    (1, 0, 1, None),
    (0, 1, 0, None),
    (0.1, 0.1, 0.2, None),
    (1, 'banana', None, TypeError),
    (1, '1', None, TypeError),
    (2, 2, 5, None))


def test_add(*, x, y, expect_sum):
    expect(x + y).to(equal(expect_sum))


execute_test_table(
    suite_name='TestAddTwoThings', table=TABLE, func=test_add)Example test table that measures performancefrom questions_three.scaffolds.test_table import execute_test_table

TABLE = (
    ('operation', 'sample size'),
    ('1 + 1', 30),
    ('1 * 1', 60),
    ('1 / 1', 42))


def calculate(operation):
    exec(operation)


execute_test_table(
    suite_name='MeasureOperatorPerformance',
    table=TABLE, func=calculate, randomize_order=True)The optionalrandomize_orderargument instructs the scaffold to execute the rows
in a random order (to mitigate systematic bias that could affect measurements).For each row that exits cleanly (no assertion failures or other exceptions),
the scaffold publishes a SAMPLE_MEASURED event that a reporter can collect.
For example, the built-in EventLogger logs each of these events, including
the row execution time.Like the other built-in scaffolds, the Test Table produces plain old Python executable scripts.Building your own scaffoldNothing stops you from building your own scaffold.  The test_script scaffold makes a good example of the services your scaffold should provide.  The xUnit scaffold is much more difficult to understand (but more fun if you're into that sort of thing).The key to understanding scaffold design is to understand theevent-driven nature of Questions Three.  Scaffolds are responsible for handling exceptions and publishing the following events:SUITE_STARTEDSUITE_ERREDSUITE_ENDEDTEST_SKIPPEDTEST_STARTEDTEST_ERREDTEST_FAILEDTEST_ENDEDReportersIn Questions Three, "reporter" is a broad term for an object that listens for an event, converts it to a message useful to someone or something and sends the message.  Built-in reporters do relatively dull things like sending events to the system log and producing the Junit XML report, but there is no reason you couldn't build a more interesting reporter that launches a Styrofoam missile at the developer who broke the build.Built-in reportersNameEvents it subscribes towhat it doesArtifact SaverARTIFACT_CREATED, REPORT_CREATEDSaves artifacts to the local filesystem.Event Loggerall test lifecycle eventsSends messages to system log.Junit Reporterall test lifecycle eventsBuilds Junit XML reports and publishes them as REPORT_CREATED events.Result Compilerall test lifecycle eventsReports how many tests ran, failed, etc, and how long they took.  Publishes SUITE_RESULTS_COMPILED after SUITE_ENDED.Custom reportersA reporter can do anything you dream up and express as Python code. That includes interacting with external services and physical objects.  Think "when this occurs during a test run, I want that to happen."  For example, "When the suite results are compiled and contain a failure, I want a Slack message sent to the channel where the developers hang out."Building a custom reporterResult Compiler provides a simple example to follow. You don't have to copy the pattern it establishes, but it's an easy way to start.  TheResultCompilerclass has one method for each event to which it subscribes.  Each method is named after the event (e.g.on_suite_started).  These method names are magic.  The importedsubscribe_event_handlersfunction recognizes the names and subscribes each method to its respective event.  Theactivatemethod is mandatory.  The scaffold calls it before the suite starts.activateperforms any initialization, most importantly subscribing to the events.Installing a custom reporterEnsure that the package containing your reporter is installed.Create a text file that contains the name of the reporter class, including its module (e.g.my_awesome_reporters.information_radiators.LavaLamp).  This file can contain as many reporters as you would like, one per line.Set the environment variableCUSTOM_REPORTERS_FILEto the full path and filename of your text file.Event BrokerThe Event Broker is Questions Three's beating heart.  It's how the components communicate with one another.  If you're not in the business of building custom components and plugging them in, you won't need to think about the Event Broker.  If you are, it's all you'll need to think about.The Event Broker is little more than a simple implementation of thePublish/Subscribe Pattern.  Component A subscribes to an event by registering a function with the Event Broker.  Component B publishes the event with an optional dictionary of arbitrary properties.  The Event Broker calls the subscriber function, passing it the dictionary as keyword arguments.An event can be any object. Internally, Questions Three limits itself to members of an enum called TestEvent.  It's defined inquestions_three.constants.An event property can also be any object. Property names are restricted to valid Python variable names so the Event Broker can send them as keyword arguments.HTTP ClientThe HTTP client is a wrapper around the widely-usedrequests module, so it can serve as a drop-in replacement. Its job in life is to integraterequestsinto the event-driven world of Questions Three, doing things like publishing an HTTP transcript when a check fails.  It also adds a few features that you can use.  Nearly all of the documentation forrequestsapplies to HttpClient as well.  There are two deviations, one significant and one somewhat obscure.Deviation 1: HTTP Client raises an exception when it encounters an exceptional status codeWhen the HTTP server returns an exceptionalstatus code(anything in the 400 - 599 range),requestssimply places the status code in the response as it always does and expects you to detect it.  HTTP Client, by contrast, detects the status for you and raises anHttpError.  There is anHttpErrorsubclass for each exceptional status code defined byRFC 7231(plus one fromRFC 2324just for fun), so you can be very specific with yourexceptblocks.  For example:from questions_three.exceptions.http_error import HttpImATeapot, HttpNotFound, HttpServerError
from questions_three.http_client import HttpClient

try:
  HttpClient().get('http://coffee.example.com')
except HttpImATeapot as e:
  # This will catch a 418 only
  # e.response is the requests.Response object returned by `requests.get`
  do_something_clever(response=e.response)
except HttpNotFound:
  # This will catch a 404 only
  do_something_sad()
except HttpServerError:
  # This will catch anything in the 500-599 range.
  do_something_silly()Deviation 2: json is not allowed as a keyword argumentrequestsallows you to write this:requests.post('http://songs.example.com/', json=['spam', 'eggs', 'sausage', 'spam'])HTTP Client does not support this syntax because it interferes with transcript generation.  Instead, write this:HttpClient().post('http://songs.example.com/', data=json.dumps(['spam', 'eggs', 'sausage', 'spam'])New feature: simplified cookie managementInstead of creating arequests.Session, you can simply do this:client = HttpClient()
client.enable_cookies()The client will now save cookies sent to it by the server and return them to the server with each request.New feature: persistent request headersThis is particularly useful for maintaining an authenticated session:client = HttpClient()
client.set_persistent_headers(session_id='some fake id', secret_username='bob')The client will now send the specified headers to the server with each request.New feature: callbacks for exceptional HTTP responsesInstead of putting each request into its own try/except block, you can install
a generic exception handler as acallback:def on_not_found(exception):
  mother_ship.beam_up(exception, exception.response.text)

client = HttpClient()
client.set_exceptional_response_callback(exception_class=HttpNotFound, callback=on_not_found)
client.get('https://something-that-does-not-exist.mil/')In the example above, the server will respond to theGETrequest with anHTTP 404(Not Found) response.  The client will notice that it has a callback for theHttpNotFoundexception, so will callon_not_foundwith theHttpNotFoundexception as theexceptionkeyword argument.If a callback returnsNone(as in the example above), the client will re-raise the exception after it processes the callback.  If the callback returns anything else, the client will return whatever the callback returns.  Please observe thePrinciple of Least Astonishmentand have your callback return eitherNoneor else anHttpResponseobject.Installed callbacks will apply to child exception classes as well, so a callback forHttpClientErrorwill be called if the server returns anHttpNotFoundresponse (becauseHttpClientErroris the set of all 4xx responses andHttpNotFoundis 404).You can install as many callbacks as you would like, with one important restriction.  You may not install a parent class or a child class of an exception that already has an associated callback.  For example, you may install bothHttpNotFoundandHttpUnauthorized, but you may not install bothHttpNotFoundandHttpClientErrorbecauseHttpClientErroris a parent class ofHttpNotFound.Seequestions_three/exceptions/http_error.pyfor complete details of the HttpError
class hierarchy. It follows the classification scheme specified in RFC 7231.Tuning with environment variablesHTTP_PROXYThis is a well-established environment variable. Set it to the URL of your proxy for plain HTTP requests.HTTPS_PROXYAs above.  Set this to the URL of your proxy for secure HTTP requestsHTTPS_VERIFY_CERTSSet this to "false" to disable verification of X.509 certificates.HTTP_CLIENT_SOCKET_TIMEOUTStop waiting for an HTTP response after this number of seconds.GraphQL ClientThe GraphQL Client is a wrapper around the HTTP Client that allows for a simple way of making and handling requests against
a GraphQL endpoint. Since the HTTP Client is doing all the heavy lifting, there is only a few custom behaviors that the GraphQL
Client has.Using the GraphQL Clientclient = HttpClient() # This is where you would authenticate, if needed
graphql_client = GraphqlClient(http_client=client, url='https://www.yoursite.com/graph')

your_important_query = """
    query {
        ...
    {
"""
graphql_client.execute(your_important_query)executeis a neutral method that makesPOSTrequests against your GraphQL endpoint for either Queries or Mutations.
The first argument ofexecuteis always the operation that you are trying to perform, and any key-word arguments
afterwards are turned into your given variables.your_important_query = """
    query ($id: String!) {
        ...
    {
"""
graphql_client.execute(your_important_query, id='1234')Upon making your request (that does not result in an HTTP Error), you will either get aGraphqlResponseobject, or
if you received errors in your response, anOperationFailedexception will be raised.GraphqlResponseobjects have the following:.http_responseproperty: Therequests.Responseobject returned by the HTTP Client.dataproperty: The JSON representation of your response.data_as_structureproperty: The Structure object representation of your responseOperationFailedexceptions have the following:.http_responseproperty: Therequests.Responseobject returned by the HTTP Client.dataproperty: The JSON representation of your (successful parts of the) response.errorsproperty: The JSON representation of the errors included in your response.operationproperty: The query or mutation sent in your request.operation_variablesproperty: The variables send in your requestWhen raised, the exception message will include the errors strings, or the entire error collectionLogging SubsystemQuestions Three extends Python's logging system to do various things internally that won't matter to most users.  However, there's one feature that may be of interest.  You can customize how verbose/noisy any given module will be.  Most common targets are event_broker when you want to see all the events passing through and http_client when you want excruciating detail about every request and response.export QUESTIONS_THREE_EVENT_BROKER_LOG_LEVEL=INFO
export QUESTIONS_THREE_HTTP_CLIENT_LOG_LEVEL=DEBUGThis works with any Questions Three module and any log level defined in theFine Python Manual.You can make it work with your custom components too:from questions_three.logging import logger_for_module

log = logger_for_module(__name__)
log.info('I feel happy!')Vanilla FunctionsYou'll find these inquestions_three.vanilla.  The unit tests undertests/vanillaprovide examples of their use.b16encode()Base 16 encode a string.  This is basically a hex dump.call_with_exception_tolerance()Execute a function. If it raises a specific exception, wait for a given number of seconds and try again up to a given timeoutformat_exception()Convert an exception to a human-friendly message and stack tracepath_to_entry_script()Return the full path and filename of the script that was called from the command linerandom_base36_string()Return a random string of a given length. Useful for generating bogus test data.string_of_sequential_characters()Return a string of letters and numbers in alphabetical order.  Useful for generating bogus but deterministic test data.url_append()Replacement forurljointhat does not eliminate characters when slashes are present but does join an arbitrary number of parts.wait_for()Pauses until the given function returns a truthy value and returns the value.  Includes a throttle and a timeout.Bulk Suite RunnerTo run all suites in any directory below./my_checks:python -m questions_three.ci.run_all my_checksControlling execution with environment variablesMAX_PARALLEL_SUITESRun up to this number of suites in parallel.  Default is 1 (serial execution).REPORTS_PATHPut reports and other artifacts in this directory.  Default:./reportsRUN_ALL_TIMEOUTAfter this number of seconds, terminate all running suites and return a non-zero exit code.TEST_RUN_IDAttach this arbitrary string as a property to all events.  This allows reporters to discriminate one test run from another.Understanding events and reports(or the philosophy of errors, failures, and warnings)Questions Three follows the convention set by JUnit and draws an important distinction between error events and failure events.  This distinction flows from the scaffolds to the Event Broker to the reports.Afailure eventoccurs when a check makes a false assertion.  The simplest way to trigger one isassert Falsewhich Python converts to anAssertionErrorwhich the scaffold converts to aTEST_FAILEDevent.  The intent of the system is to produce a failure event only when there is high confidence that there is a fault in the system under test.Anerror eventoccurs when some other exception gets raised (or, for whatever batty reason, something other than a check raises anAssertionError).  Depending on the context from which the exception was raised, the scaffold will convert it into aSUITE_ERREDor aTEST_ERREDevent.  In theory, an error event should indicate a fault in the check.  In practice, the fault could be anywhere, especially if the system under test behaves in unanticipated ways.Because of the expectation that failure events indicate faults in the checks and error events indicate faults in the system under test, theEvent Loggerreports failure events as warnings and error events as errors.  The warning indicates that the check did its job perfectly and the fault was somewhere else.  The error indicates that the fault is in the check.  Of course, real life is not so clean.Because the distinction originated from the JUnit world,Junit XML Reporterhas no need to perform any interpretation.  It reports failure events as failures and error events as errors.