mysql_info: Explanation unit-test

[rndmh3ro]

As per discussion here: #115

I'm trying to understand how this unit test works.

@pytest.mark.parametrize(
    'suffix,cursor_output',
    [
        ('mysql', '5.5.1-mysql'),
        ('log', '5.7.31-log'),
        ('mariadb', '10.5.0-mariadb'),
        ('', '8.0.22'),
    ]
)
def test_get_info_suffix(suffix, cursor_output):
    def __cursor_return_value(input_parameter):
        if input_parameter == "SHOW GLOBAL VARIABLES":
            cursor.fetchall.return_value = [{"Variable_name": "version", "Value": cursor_output}]
        else:
            cursor.fetchall.return_value = MagicMock()

    cursor = MagicMock()
    cursor.execute.side_effect = __cursor_return_value

    info = MySQL_Info(MagicMock(), cursor)

    assert info.get_info([], [], False)['version']['suffix'] == suffix

We have a function __cursor_return_value that accepts an input parameter. If this parameter is SHOW GLOBAL VARIABLES then the return_value dict is populated with the global varibles. If the input_parameter is not SHOW GLOBAL VARIABLES then the return_value is MagicMock() - what does this mean? What value does return_value have?

After the function definition it gets executed (without parameters):

    cursor = MagicMock()
    cursor.execute.side_effect = __cursor_return_value

Question: why side_effect?

Then the module gets executed:

info = MySQL_Info(MagicMock(), cursor)

Again the MagicMock(). And cursor those value is MagicMock(), too?

Last the assert:

    assert info.get_info([], [], False)['version']['suffix'] == suffix

There a comparision is done. However I don't understand what info.get_info([], [], False)['version']['suffix'] means. suffix is probably from @pytest.mark.parametrize, right? And I guess, the test gets executed for all items in @pytest.mark.parametrize?

[Jorge-Rodriguez]

Let's take this one step at a time:
MagicMock() is part of the standard unittest.mock library and it's its implementation of a mock object, the purpose of which is to replace an actual object with a simulation whose behavior we can control.

When a method is called on a MagicMock instance, the default behavior is to return another MagickMock object. Generally you can modify this behaviour by setting the return_value attribute. When the desired effects of a call on a particular method of the MagicMock class are more complex than simply returning a value, e.g. the value needs to change in subsequent calls, an exception needs to be raised, or any other complex behaviour, this can be accomplished by setting the side_effect attribute instead. If side_effect is a function, it will be called with the same parameters as the call on the mocked method, so if we had the following object:

class Foo():
  def bar(a,b)

foo = Foo()
foo.bar(1, 2)

And we mocked it as such:

def side_effect(*args):
  pass

foo = MagicMock(side_effect=side_effect)

Then side_effect will be called with argumens (1, 2).

Now, on to our code, there's a bunch of magic here:
First, the __cursor_return_value function. The problem is as follows:
We are trying to simulate the behaviour of a database cursor, but this is not quite straight forward because cursors work in two stages; first there's a call to execute with whatever SQL query we want to run as parameter and then there's a subsequent call to one of the fetch* methods to retrieve the results.
This is why we're using a side effect on the execute call which has no (usable) return value.
Because the side effect function receives only the parameters sent to the original call (execute in this case) we generally wouldn't be able to access the mock object cursor from within the function to modify its behaviour but, because we've defined __cursor_return_value as an inner function on the test, we can access all of the variables of its parent's scope. This is how the side effect works.

If the cursor's execute method is called with SHOW GLOBAL VARIABLES, which is the call we're looking for, then we return a dictionary of global variables similar to what the real cursor would do. Since we're only interested in the version string, we don't bother with the long list of other global variables.
If the cursor's execute method is called with any other parameters, we don't really care about the return value, so we return a MagicMock object which is the default behaviour as we saw above. This is useful because the code does use this return value and with a mock object any calls on the return value will run properly and return mock objects in turn. This is a bit convoluted but the gist is that by returning a mock object we no longer need to concern ourselves with what it's done in the cases we're not interested in.

After the function is defined, we define the variable cursor as a MagicMock and then we assign the __cursor_return_value as a side effect to cursor's execute method. The side effect function is NOT executed here.

Then we instantiate info as a MySQL_Info object. The constructor of the MySQL_Info object takes two parameters, a module and a cursor. Since we do not much care for the module part, we pass an anonymous mock object to the constructor. The cursor parameter is also a mock object, but this one is named because we do want to manage its behaviour. The module is NOT executed here.

Finally, in the assert line, we call info.get_info([], [], False). The parameters to get_info control what kind of info is retrieved from the database, but that isn't much use in this case, since we've mocked the cursor and that's going to return whatever we tell it to do (which is a mock object most of the time). This IS where the module gets executed, and by extension, this is also where the __cursor_return_value side effect function gets called.

The call to get_info returns a dictionary. In this dictionary the version key holds yet another dictionary with all the bits of the server version information. Of all those we're only interested in the suffix, which is the key we're selecting with info.get_info([], [], False)['version'}['suffix'] the assertion itself verifies that the value of that key, returned by the get_info function matches our expectation, which is passed as the suffix parameter to the test function.

To wrap up, the decorator @pytest.mark,parametrize is a nice and elegant way of running the same test against multiple sets of inputs (and outputs). In our case, we're defining a list of tuples that contain, in this order, the suffix we expect from the get_info function, and the version string "returned" by the database server (actually by our cursor mock object). On execution of the test suite, pytest will run one test for each tuple defined in the decorator.