diff --git a/docs/docs/getting_started.rst b/docs/docs/getting_started.rst index b11da7c83..df50a696d 100644 --- a/docs/docs/getting_started.rst +++ b/docs/docs/getting_started.rst @@ -1,5 +1,10 @@ .. _getting_started: + +.. role:: raw-html(raw) + :format: html + + ========================= Getting Started with Moto ========================= @@ -223,7 +228,7 @@ You need to ensure that the mocks are actually in place. #. **VERY IMPORTANT**: ensure that you have your mocks set up *BEFORE* your `boto3` client is established. This can typically happen if you import a module that has a `boto3` client instantiated outside of a function. - See the pesky imports section below on how to work around this. + See :ref:`pesky_imports_section` below on how to work around this. .. note:: By default, the region must be one supported by AWS, see :ref:`Can I mock the default AWS region?` for how to change this. @@ -267,17 +272,30 @@ Next, once you need to do anything with the mocked AWS environment, do something assert len(result["Buckets"]) == 1 assert result["Buckets"][0]["Name"] == "somebucket" + +.. _pesky_imports_section: + What about those pesky imports ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Recall earlier, it was mentioned that mocks should be established __BEFORE__ the clients are set up. One way -to avoid import issues is to make use of local Python imports -- i.e. import the module inside of the unit -test you want to run vs. importing at the top of the file. +As mentioned earlier, mocks should be established __BEFORE__ the clients are set up. + +Some background on why this is necessary: :raw-html:`
` +Moto intercepts HTTP requests using a custom event handler that hooks into botocore's event-system. :raw-html:`
` +When creating clients/resources, `boto3` gathers all event handlers that have been registered at that point, and injects those handlers into the created client/resource. Event handlers registered after a client is created, are not used. + +The `moto.core`-package registers our event handler on initialization. So to be pedantic: `moto.core` should be imported before a client is created, in order for `boto3` to call our custom handler and therefore for Moto to be active. :raw-html:`
` +The easiest way to ensure this happens, is to establish a mock before the clients are setup, as `moto.core` is imported when the mock starts. + + +One way to avoid import issues is to make use of local Python imports -- i.e. import the module that creates boto3-clients inside of the unit test you want to run. Example: .. sourcecode:: python def test_something(s3): + # s3 is a fixture defined above that yields a boto3 s3 client. + from some.package.that.does.something.with.s3 import some_func # <-- Local import for unit test # ^^ Importing here ensures that the mock has been established. diff --git a/docs/docs/server_mode.rst b/docs/docs/server_mode.rst index 018fd8d04..992172688 100644 --- a/docs/docs/server_mode.rst +++ b/docs/docs/server_mode.rst @@ -93,6 +93,7 @@ Run using Docker ---------------------- You could also use the official Docker image. This is stored in two different repositories: + - https://hub.docker.com/r/motoserver/moto/tags - https://github.com/getmoto/moto/pkgs/container/motoserver