Python’s unittest.mock library is a instrument that helps you create mock objects to simulate complicated logic and unpredictable dependencies.
This helps you write beneficial assessments that confirm your software logic is right, dependable, and environment friendly.
You’ll start by studying about what mocking is and the way you need to use it to enhance your assessments.
What Is Mocking?
A mock object substitutes and imitates an actual object inside a testing atmosphere. Utilizing mock objects is a flexible and highly effective method to enhance the standard of your assessments. It is because through the use of Python mock objects, you’ll be able to management your code’s habits throughout testing.
For instance, in case your code makes HTTP requests to exterior companies, then your assessments execute predictably solely as far as the companies are behaving as you anticipated. Generally, a short lived change within the habits of those exterior companies could cause intermittent failures inside your take a look at suite.
Due to this, it will be higher so that you can take a look at your code in a managed atmosphere. Changing the precise request with a mock object would can help you simulate exterior service outages and profitable responses in a predictable approach.
Generally, it’s tough to check sure areas of your codebase. Such areas embody besides blocks and if statements which are laborious to fulfill. Utilizing Python mock objects might help you management the execution path of your code to succeed in these areas and enhance your code protection.
Another excuse to make use of mock objects is to higher perceive the way you’re utilizing their actual counterparts in your code. A Python mock object accommodates information about its utilization which you can examine, akin to:
- In the event you referred to as a technique
- The way you referred to as the tactic
- How typically you referred to as the tactic
Understanding what a mock object does is step one to studying easy methods to use one.
Subsequent, you’ll discover the Python mock object library to see easy methods to use Python mock objects.
The Python Mock Library
Python’s built-in mock object library is unittest.mock. It supplies a straightforward method to introduce mocks into your assessments.
Observe: The usual library contains unittest.mock ranging from Python 3.3 and in all newer variations. In the event you’re utilizing an older model of Python, then you definitely’ll want to put in the official backport of the library.
To take action, set up mock from the Python Bundle Index (PyPI) utilizing pip:
It’s possible you’ll need to create and activate a digital atmosphere earlier than putting in the bundle.
unittest.mock supplies a category referred to as Mock, which you’ll use to mimic actual objects in your codebase. Mock, together with its subclasses, provides unimaginable flexibility and insightful information that can meet most of your Python mocking wants.
The library additionally supplies a operate referred to as patch(), which replaces the actual objects in your code with Mock situations. You need to use patch() as both a decorator or a context supervisor, supplying you with management over the scope by which the item might be mocked. As soon as the designated scope exits, patch() will clear up your code by changing the mocked objects with their authentic counterparts.
Lastly, unittest.mock supplies options for a number of the points inherent in mocking objects, which you’ll discover later on this tutorial.
Now that you’ve a greater understanding of what mocking is and the library you’ll be utilizing, it’s time to dive in and discover the options and functionalities unittest.mock has to supply.
The Mock Object
unittest.mock provides a base class for mocking objects referred to as Mock. The use circumstances for Mock are virtually limitless as a result of Mock is so versatile.
Start by instantiating a brand new Mock occasion:
Now, you’re capable of substitute an object in your code along with your new Mock. You are able to do this by passing it as an argument to a operate or by redefining one other object:
Whenever you substitute an object in your code, the Mock should seem like the actual object it’s changing. In any other case, your code will be unable to make use of the Mock instead of the unique object.
For instance, should you’re mocking the json library and your program calls dumps(), then your Python mock object should additionally include dumps(). Subsequent, you’ll see how Mock offers with this problem.
Understanding Lazy Attributes and Strategies
A Mock should simulate any object that it replaces. To realize such flexibility, it creates its attributes if you entry them :
Since Mock can create arbitrary attributes on the fly, it’s capable of exchange any object.
Utilizing an instance from earlier, should you’re mocking the json library and also you name dumps(), the Python mock object will create the tactic in order that its interface can match the library’s interface:
Discover two key traits of this mocked model of dumps():
-
In contrast to the actual
dumps(), this mocked technique requires no arguments. In truth, it would settle for any arguments that you simply move to it. -
The return worth of
.dumps()can also be aMock.
The potential of Mock to recursively outline different mocks permits so that you can use mocks in complicated conditions:
As a result of the return worth of every mocked technique can also be a Mock, you need to use your mocks in a mess of the way.
Mocks are versatile, however they’re additionally informative. Subsequent, you’ll learn the way you need to use mocks to grasp your code higher.
Leveraging Assertions and Inspection
Mock situations retailer information on the way you used them. For instance, they can help you see should you referred to as a technique, the way you referred to as the tactic, and so forth. There are two primary methods to make use of this info:
- Assertions can help you assert that you simply used an object as anticipated.
- Inspection means that you can to view particular attributes to grasp how your software used an object.
First, you’ll have a look at how you need to use assertions. Arrange a brand new Mock object, once more to mock the json library, then name .masses():
You’ve created a brand new Mock, mock.masses(), and referred to as it. Now you can make assertions to check your expectations that you simply referred to as .masses() as soon as:
All assertions move with out elevating an AssertionError. Attempt to name .masses() once more and likewise repeat the decision to .assert_called_once():
Your assertion .assert_called_once() fails and raises an AssertionError since you referred to as .masses() two occasions.
A mock object comes with a wide range of assertion strategies, akin to:
.assert_called(): Ensures that you simply referred to as the mocked technique..assert_called_once(): Checks that you simply referred to as the tactic precisely one time..assert_not_called(): Ensures that you simply by no means referred to as the mocked technique.
It additionally has comparable strategies that allow you to examine the arguments handed to the mocked technique:
.assert_called_with(*args, **kwargs).assert_called_once_with(*args, **kwargs)
To move these assertions, you need to name the mocked technique with the identical arguments that you simply move to the precise technique.
This method can break if you specify the arguments in another way in each calls, even should you present the identical arguments:
You may see that the primary name to .assert_called_with() raised an AssertionError as a result of it anticipated you to name .masses() with a positional argument, however you truly referred to as it with a key phrase argument. Whenever you name .assert_called_with() the second time, utilizing the key phrase argument, the assertion passes.
Outfitted with these built-in strategies on a Mock, you’ll be able to come a great distance in asserting that your program used an object as you anticipated. However there’s much more you are able to do.
You may introspect your Mock by accessing particular attributes. This provides you a good higher concept of how your software used an object.
Begin by making a recent mock and calling .masses() on it once more:
As an alternative of utilizing assertion strategies like earlier than, you’ll be able to examine the worth of some particular attributes:
You may write assessments utilizing these attributes to make it possible for your objects behave as you supposed.
Now, you’ll be able to create mocks and examine their utilization information. Subsequent, you’ll see easy methods to customise mocked strategies in order that they turn out to be extra helpful in your testing atmosphere.
Managing a Mock’s Return Worth
One motive to make use of mocks is to manage your code’s habits throughout assessments. A technique to do that is to specify a operate’s return worth. Let’s use an instance to see how this works.
First, create a file referred to as holidays.py. Add is_weekday(), a operate that makes use of Python’s datetime library to find out whether or not or not as we speak is a weekday. Lastly, write a take a look at that asserts that the operate works as anticipated:
Because you’re testing if as we speak is a weekday, the outcome is dependent upon the day you run your take a look at:
If this command produces no output, the assertion was profitable. Sadly, should you run the command on a weekend, you’ll get an AssertionError:
When writing assessments, you will need to be sure that the outcomes are predictable. You need to use Mock to remove uncertainty out of your code throughout testing. On this case, you’ll be able to mock datetime and set the .return_value for .as we speak() to a day that you simply select:
Within the instance, .as we speak() is a mocked technique. You’ve eliminated the inconsistency by assigning a selected day to the mock’s .return_value. That approach, if you name .as we speak(), it returns the datetime that you simply specified.
Within the first take a look at, you guarantee wednesday is a weekday. Within the second take a look at, you confirm that sunday isn’t a weekday. Now, it doesn’t matter what day you run your assessments since you’ve mocked datetime and have management over the item’s habits.
Observe: Although mocking datetime like this can be a good follow instance for utilizing Mock, a unbelievable library already exists for mocking datetime referred to as freezegun.
Now that you understand how to mock a operate’s return worth, you’ll be able to write predictable assessments in your code, even when it is dependent upon unpredictable exterior circumstances.
Whenever you write assessments in your program, you usually place them in a separate file. Following good follow, you’d arrange a test_holidays.py to separate the vacation calendar logic out of your testing logic, and import the capabilities from holidays.py:
Nevertheless, should you do that, then the crude method to mocking that you simply’ve seen up to now will break your take a look at code:
The explanation for this error comes from the way you mocked the datetime module in your take a look at file. Whenever you import a module in one other module, the imported names are sure to that module’s namespace. Mocking datetime in your take a look at file doesn’t have an effect on datetime in is_weekday() as a result of holidays.py has already imported the actual datetime module.
To accurately mock datetime in holidays.py, you need to patch datetime within the namespace the place it’s used. The unittest.mock library’s patch() operate is helpful for this goal. You’ll discover ways to use patch() in a while. For now, you’ll proceed mocking proper inside holidays.py to keep away from this subject.
When constructing your assessments, you’ll seemingly come throughout circumstances the place mocking a operate’s return worth is not going to be sufficient. It is because capabilities are sometimes extra difficult than a easy one-way stream of logic.
Generally, you’ll need to make capabilities return totally different values if you name them greater than as soon as and even elevate exceptions. You are able to do this utilizing .side_effect.
Managing a Mock’s Aspect Results
You may management your code’s habits by specifying a mocked operate’s unintended effects. A .side_effect defines what occurs if you name the mocked operate.
To check how this works, add a brand new operate to holidays.py:
On this instance, get_holidays() makes a request to the localhost server for a set of holidays. If the server responds efficiently, get_holidays() will return a dictionary. In any other case, the tactic will return None.
You may take a look at how get_holidays() will reply to a connection timeout by setting requests.get.side_effect.
For this instance, you’ll solely see the related code from holidays.py. You’ll construct a take a look at case utilizing Python’s unittest library:
You employ .assertRaises() to confirm that get_holidays() raises an exception given the brand new aspect impact of .get().
Run this take a look at to see the results of your take a look at:
If you wish to be a little bit extra dynamic, you’ll be able to set .side_effect to a operate that Mock will invoke if you name your mocked technique. The mock shares the arguments and return worth of the .side_effect operate:
First, you created .log_request(), which takes a URL, logs some output utilizing print(), then returns a Mock response. Subsequent, you set the .side_effect of .get() to .log_request(), which you’ll use if you name get_holidays(). Whenever you run your take a look at, you’ll see that .get() forwards its arguments to .log_request(), then accepts the return worth and returns it:
Nice! The calls to print() logged the right values. Additionally, get_holidays() returned the vacations dictionary.
.side_effect may also be an iterable. The iterable should encompass return values, exceptions, or a combination of each. The iterable will produce its subsequent worth each time you name your mocked technique. For instance, you’ll be able to take a look at {that a} retry after a Timeout returns a profitable response:
Whenever you run the up to date file, you’ll see that the brand new take a look at case, .test_get_holidays_retry(), passes as properly:
The primary time you name get_holidays(), .get() raises a Timeout. The second time, the tactic returns a legitimate holidays dictionary. These unintended effects match the order they seem within the record handed to .side_effect.
You may set .return_value and .side_effect on a Mock straight. Nevertheless, as a result of a Python mock object must be versatile in creating its attributes, there’s a greater method to configure these and different settings.
Configuring Your Mock
You may configure a Mock to arrange a number of the object’s behaviors. Some configurable members embody .side_effect, .return_value, and .identify. You configure a Mock if you create one or if you use .configure_mock().
You may configure a Mock by specifying sure attributes if you initialize an object:
As you’ve seen within the earlier part, you’ll be able to set .side_effect and .return_value straight on the Mock occasion itself after initialization.
Another attributes, such because the identify of your Mock, you’d primarily set when initializing the item, like proven above. In the event you attempt to set the .identify of the Mock on the occasion, you’ll get a distinct outcome than what you may anticipate:
The identify .identify is a typical attribute in objects. So, Mock doesn’t allow you to set that worth on the occasion in the identical approach you’ll be able to with .return_value or .side_effect. In the event you entry mock.identify, you’ll create a .identify attribute as a substitute of configuring your mock.
Observe: To keep away from identify clashes, Mock mangles some names, akin to identify, earlier than saving them on the occasion. You may entry and edit that attribute on the occasion by way of ._mock_name.
Nevertheless, observe that the main underscore alerts that it’s a personal attribute and, due to this fact, not supposed so that you can straight entry and edit.
Normally, if you wish to configure an present Mock, you need to use .configure_mock():
By unpacking a dictionary into both a name to .configure_mock() or Mock.__init__(), you’ll be able to even configure your Python mock object’s attributes.
Utilizing Mock configurations, you could possibly simplify a earlier instance:
Now, you’ll be able to create and configure Python mock objects. You may also use mocks to manage the habits of your software. To date, you’ve used mocks as arguments to capabilities or patching objects in the identical module as your assessments.
Subsequent, you’ll discover ways to substitute your mocks for actual objects in different modules.
The patch() Perform
The unittest.mock library supplies a strong mechanism for mocking objects, referred to as patch(), which appears to be like up an object in a given module and replaces that object with a Mock.
Often, you employ patch() as a decorator or a context supervisor to supply a scope by which you’ll mock the goal object.
Utilizing patch() as a Decorator
If you wish to mock an object during your complete take a look at operate, then you need to use patch() as a operate decorator.
To see how this works, reorganize your holidays.py file by placing the logic and assessments into separate information:
The capabilities of your module at the moment are in their very own file, separate from their assessments. Subsequent, you’ll re-create your assessments in a file referred to as test_holidays.py.
Up so far, you’ve monkey patched objects within the file by which they exist. Monkey patching is the alternative of 1 object with one other at runtime. Now, you’ll use patch() to switch your objects in holidays.py from inside your take a look at file:
Initially, you created a Mock and patched requests within the native scope. Now, it’s essential to entry the requests library in holidays.py from assessments.py.
On this case, you used patch() as a decorator and handed the goal object’s path. The goal path was "holidays.requests", which consists of the module identify and the item.
You additionally outlined a brand new parameter, mock_requests, for the take a look at operate. patch() makes use of this parameter to move the mocked object into your take a look at. From there, you’ll be able to modify the mock or make assertions as needed.
You may execute this take a look at module to make sure it’s working as anticipated:
Nice! The take a look at case passes, which implies that you’ve efficiently changed the requests library within the scope of holidays with a Mock object.
Observe: The patch() operate returns an occasion of MagicMock, which is a Mock subclass. MagicMock is helpful as a result of it implements most magic strategies for you, akin to .__len__(), .__str__(), and .__iter__(), with cheap defaults.
Utilizing patch() as a decorator labored properly on this instance. In some circumstances, it’s extra readable or simpler to make use of patch() as a context supervisor.
Utilizing patch() as a Context Supervisor
Generally, you’ll need to use patch() as a context supervisor reasonably than a decorator. Some explanation why you may desire a context supervisor embody the next:
- You solely need to mock an object for part of the take a look at scope.
- You’re already utilizing too many decorators or parameters, which hurts your take a look at’s readability.
To make use of patch() as a context supervisor, you employ Python’s with assertion:
Utilizing this method, Python will mock the requests library in holidays solely throughout the context supervisor. When the take a look at exits the with assertion, patch() replaces the mocked object once more with the unique.
Till now, you’ve mocked full objects, however typically you’ll solely need to mock part of an object.
Patching an Object’s Attributes
In the event you solely need to mock one technique of an object as a substitute of the complete object, you are able to do so through the use of patch.object().
For instance, .test_get_holidays_timeout() actually solely must mock requests.get() and set its .side_effect to Timeout:
On this instance, you’ve mocked solely get() reasonably than all of requests. Each different attribute stays the identical.
object() takes the identical configuration parameters that patch() does. However as a substitute of passing the goal’s path, you present the goal object itself as the primary parameter. The second parameter is the attribute of the goal object that you simply’re attempting to mock. You may also use object() as a context supervisor like patch().
Observe: Apart from objects and attributes, you too can patch() dictionaries with patch.dict().
Studying easy methods to use patch() is crucial to mocking objects in different modules. Nevertheless, typically it’s not apparent what the goal object’s path is.
Understanding The place to Patch
Understanding the place to inform patch() to search for the item you need mocked is vital as a result of should you select the improper goal location, then the results of patch() could possibly be one thing you didn’t anticipate.
Let’s say you might be mocking is_weekday() in holidays.py utilizing patch():
First, you import holidays.py. Then you definitely patch is_weekday(), changing it with a Mock. Nice! That is working as anticipated.
Now, you’ll do one thing barely totally different and import the operate straight:
This time, the output isn’t a Mock like earlier than.
Observe: Relying on what day you’re studying this tutorial, your console output could learn True or False.
Discover that regardless that the goal location you handed to patch() didn’t change, the results of calling is_weekday() is totally different. The distinction comes from the change in the way you imported the operate.
Whenever you use from holidays import is_weekday, you bind the is_weekday() to the native scope. So, regardless that you patch() the operate later, you ignore the mock as a result of you have already got an area reference to the unmocked operate.
A good rule of thumb is to patch() the item the place it’s regarded up.
Within the first instance, mocking "holidays.is_weekday()" works since you search for the operate within the holidays module. Within the second instance, you have got an area reference to is_weekday(). Since you employ the operate discovered within the native scope, you need to mock the native operate:
On this instance, you’ve patched the operate within the native scope which you can entry by __main__. Due to this, your mock labored as anticipated.
Now, you have got a agency grasp on the facility of patch(). You’ve seen easy methods to patch() objects and attributes in addition to the place to patch them. Subsequent, you’ll see some widespread issues inherent in object mocking and the options that unittest.mock supplies.
Widespread Mocking Issues
Mocking objects can introduce a number of issues into your assessments. Some issues are inherent in mocking whereas others are particular to unittest.mock. Remember the fact that there are different points with mocking that aren’t talked about on this tutorial.
Those coated listed here are comparable in that the issues they trigger are essentially the identical. In every case, the take a look at assertions are irrelevant. Although the intention of every mock is legitimate, the mocks themselves aren’t.
Modifications to Object Interfaces and Misspellings
Courses and performance definitions change on a regular basis. When the interface of an object adjustments, any assessments counting on a Mock of that object could turn out to be irrelevant.
For instance, you rename a technique however overlook {that a} take a look at mocks that technique and invokes .assert_not_called(). After the change, .assert_not_called() remains to be True. Nevertheless, the assertion isn’t helpful as a result of the tactic now not exists.
Irrelevant assessments could not sound crucial, but when they’re your solely assessments and also you assume that they work correctly, the scenario could possibly be disastrous in your software.
An issue particular to Mock is {that a} misspelling can break a take a look at. Recall {that a} Mock creates its interface if you entry its members. So, should you misspell its identify, you’ll inadvertently create a brand new attribute.
For instance, should you misspell .assert_called() by as a substitute typing .asst_called(), then your take a look at gained’t elevate an AssertionError. It is because you’ve created a brand new technique on the Python mock object named .asst_called() as a substitute of evaluating an precise assertion.
Observe: Apparently, the builders of unittest.mock deal with a listing of widespread misspellings of assert.
In the event you attempt to entry an attribute that begins with, for instance, assret, then Mock will mechanically elevate an AttributeError with an informative error message declaring that you simply in all probability misspelled assert.
The issues talked about on this part happen if you mock objects inside your personal codebase. A special drawback arises if you mock objects that work together with exterior codebases.
Modifications to Exterior Dependencies
Think about once more that your code makes a request to an exterior API. On this case, the exterior dependency is the API which is vulnerable to vary with out your consent.
On one hand, what unit assessments are there for is to check remoted parts of code. So, mocking the code that makes the request lets you take a look at your remoted parts below managed situations. Nevertheless, it additionally presents a possible drawback.
If an exterior dependency adjustments its interface, your Python mock objects will turn out to be invalid. If this occurs and the interface change is a breaking one, your assessments will move as a result of your mock objects have masked the change, however your manufacturing code will fail.
Sadly, this isn’t an issue that unittest.mock supplies an answer for. You have to train judgment when mocking exterior dependencies.
All of those points could cause take a look at irrelevancy and doubtlessly pricey points as a result of they threaten the integrity of your mocks. Whereas unittest.mock can’t totally keep away from these issues, it offers you some instruments for coping with them.
Avoiding Widespread Issues Utilizing Specs
As talked about earlier than, should you change a category or operate definition or misspell a Python mock object’s attribute, you’ll be able to trigger issues along with your assessments.
These issues happen as a result of Mock creates attributes and strategies lazily if you entry them. The reply to those points is to stop Mock from creating attributes that don’t conform to the item you’re attempting to mock.
When configuring a Mock, you’ll be able to move an object specification to the spec parameter. The spec parameter accepts a listing of names or one other object and defines the mock’s interface. In the event you try and entry an attribute that doesn’t belong to the specification, Mock will elevate an AttributeError:
Right here, you’ve specified that fake_holidays has two strategies referred to as .is_weekday() and .get_holidays(). Whenever you entry .is_weekday(), it returns a Mock. Nevertheless, if you entry .create_event(), a technique that doesn’t match the specification, then Mock raises an AttributeError.
Specs work the identical approach should you configure the Mock with an object:
The .is_weekday() technique is obtainable to your fake_holidays mock since you configured the Mock to match the interface of your holidays module.
unittest.mock additionally supplies handy methods to mechanically specify the interface of a Mock occasion.
One method to implement computerized specs is with create_autospec():
Like earlier than, fake_holidays is a Mock occasion whose interface matches holidays. This time, you created it utilizing create_autospec() and also you’ll discover that .is_weekday() is a MagicMock as a substitute.
In the event you’re utilizing patch(), then you’ll be able to set the autospec parameter to True to attain the identical outcome:
Once more, your mock of holidays mechanically adopted the module’s specification and arrange guardrails to stop you from unintentionally creating objects that don’t match that specification.
Conclusion
On this tutorial, you’ve discovered a lot about mocking objects utilizing unittest.mock!
Now, you’re capable of:
- Use
Mockto imitate objects in your assessments - Verify utilization information to grasp how you employ your objects
- Customise your mock objects’ return values and unintended effects
- Use
patch()objects all through your codebase - Determine and keep away from issues with utilizing Python mock objects
You’ve constructed a basis of understanding that can assist you construct higher assessments. Now, you need to use mocks to achieve insights into your code that you simply wouldn’t have in any other case had.
Disclaimer: Watch out for overusing mocks! It’s straightforward to make the most of the facility of Python mock objects. In the event you mock an excessive amount of, then you might lower the worth of your assessments.
Carry on studying about unittest and unittest.mock to construct your data and instinct for writing higher assessments in Python.
Take the Quiz: Take a look at your data with our interactive “Understanding the Python Mock Object Library” quiz. You’ll obtain a rating upon completion that can assist you observe your studying progress:
Interactive Quiz
Understanding the Python Mock Object Library
On this quiz, you may take a look at your understanding of Python’s unittest.mock library. With this data, you can write sturdy assessments, create mock objects, and guarantee your code is dependable and environment friendly.
