Python 2.7 has reached end of supportand will bedeprecatedon January 31, 2026. After deprecation, you won't be able to deploy Python 2.7applications, even if your organization previously used an organization policy tore-enable deployments of legacy runtimes. Your existing Python2.7 applications will continue to run and receive traffic after theirdeprecation date. We recommend thatyoumigrate to the latest supported version of Python.

google.appengine.ext.testbed package

Summary

A module to use service stubs for testing.

To test applications that use App Engine services, such as datastore, developers can use the available stub implementations. Service stubs behave like the original service without causing permanent side effects. The datastore stub, for example, allows you to write entities into memory without storing them to the actual datastore. The testbed module makes using those stubs for testing easier.

Example:

importunittestfromgoogle.appengine.extimportndbfromgoogle.appengine.extimporttestbedclassTestModel(ndb.Model):number=ndb.IntegerProperty(default=42)classMyTestCase(unittest.TestCase):defsetUp(self):# First, create an instance of the Testbed class.self.testbed=testbed.Testbed()# Then activate the testbed, which will allow you to use# service stubs.self.testbed.activate()# Next, declare which service stubs you want to use.self.testbed.init_datastore_v3_stub()self.testbed.init_memcache_stub()deftearDown(self):# Don't forget to deactivate the testbed after the tests are# completed. If the testbed is not deactivated, the original# stubs will not be restored.self.testbed.deactivate()deftestInsertEntity(self):# Because we use the datastore stub, this put() does not have# permanent side effects.TestModel().put()fetched_entities=TestModel.query().fetch(2)self.assertEqual(1,len(fetched_entities))self.assertEqual(42,fetched_entities[0].number)
Enable stubs and disable services
The testbed module allows you to use stubs for the following services:

  • capability_service

  • channel

  • datastore_v3 (aka datastore)

  • images (only for dev_appserver)

  • mail (only for dev_appserver)

  • memcache

  • taskqueue

  • urlfetch

  • user

  • xmpp

To use a particular service stub, callself.init_SERVICENAME_stub(). Using this call will replace calls to the service with calls to the service stub. If you want to disable any calls to a particular service, callself.init_SERVICENAME_stub(enable=False). This call can be useful if you want to test code that must not use a certain service.

Environment variables

App Engine service stubs often depend on environment variables. For example, the datastore stub usesos.environ[‘APPLICATION_ID’] to store entities linked to a particular app. testbed will use default values if nothing else is provided, but you can change those values withself.setup_env().

classgoogle.appengine.ext.testbed.EmulatorSupportCheckersource

Bases: object

A static class. Checks whether datastore emulator is supported.

classmethodcheck()source

Checks whether cloud datastore should be used.

In a unittest test process, the first call to this method sets the value of _use_datastore_emulator and _api_port. Subsequent calls to this method can read _use_datastore_emulator.

Returns

A boolean that indicates whether cloud datastore should be used.

classmethodget_api_port()source

Returns the integer port number that api_server listens on.

classmethodget_emulator_port()source

Returns the integer port number that datastore emulator listens on.

classmethodinit(api_port, emulator_port)source
exceptiongoogle.appengine.ext.testbed.Errorsource

Bases: exceptions.Exception

Base testbed error type.

exceptiongoogle.appengine.ext.testbed.NotActivatedErrorsource

Bases:google.appengine.ext.testbed.Error

Raised if the used testbed instance is not activated.

exceptiongoogle.appengine.ext.testbed.StubNotSupportedErrorsource

Bases:google.appengine.ext.testbed.Error

Raised if an unsupported service stub is accessed.

classgoogle.appengine.ext.testbed.Testbedsource

Bases: object

Class providing APIs to manipulate stubs for testing.

This class allows you to replace App Engine services with fake stub implementations. These stubs act like the actual APIs but do not invoke the replaced services.

In order to use a fake service stub or disable a real service, invoke the correspondinginit_*_stub methods of this class.

activate(use_datastore_emulator=False)source

Activates the testbed.

Invoking this method will also assign default values to environment variables that are required by App Engine services, such asos.environ[‘APPLICATION_ID’]. You can set custom values withsetup_env().

Parameters

use_datastore_emulator – True if user specifies testbed to use the Cloud Datastore Emulator.

deactivate()source

Deactivates the testbed.

This method will restore the API proxy and environment variables to the state they were in beforeactivate() was called.

Raises

NotActivatedError – If called beforeactivate() was called.

get_stub(service_name)source

Gets the stub for a service.

Parameters

service_name – The name of the service.

Returns

The stub forservice_name.

Raises
init_all_stubs(enable=True)source

Enables all known testbed stubs.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_app_identity_stub(enable=True)source

Enables the app identity stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_blobstore_stub(enable=True)source

Enables the blobstore stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_capability_stub(enable=True)source

Enables the capability stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_channel_stub(enable=True)source

Enables the channel stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_datastore_v3_stub(enable=True, datastore_file=None, use_sqlite=False, auto_id_policy='sequential', **stub_kw_args)source

Enables the datastore stub.

Thedatastore_file argument can be set to the path of an existing datastore file, orNone (default) to use an in-memory datastore that is initially empty. If you use the sqlite stub and have defineddatastore_file, the changes that you apply in a test will be written to the file. If you use the default datastore stub, changes are not saved to disk unless you setsave_changes=True.

Note:

You can only access those entities of the datastore file that use the same application ID as the test run. You can change the application ID for a test withsetup_env().

Parameters

  • enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

  • datastore_file – File name of a dev_appserver datastore file.

  • use_sqlite –True to use the Sqlite stub, orFalse (default) to use the file stub.

  • auto_id_policy – How datastore stub assigns auto IDs. This value can be eitherAUTO_ID_POLICY_SEQUENTIAL orAUTO_ID_POLICY_SCATTERED.

  • **stub_kw_args – Keyword arguments passed on to the service stub.

Raises

StubNotSupportedError – If datastore_sqlite_stub is None.

init_files_stub(enable=True)source

Enables the Files API stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_images_stub(enable=True, **stub_kwargs)source

Enables the images stub.

The images service stub is only available in dev_appserver because it uses the PIL library.

Parameters

  • enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

  • **stub_kwargs – Keyword arguments passed on to the service stub.

init_logservice_stub(enable=True)source

Enables the log service stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

Raises

StubNotSupportedError – The logservice stub is unvailable.

init_mail_stub(enable=True, **stub_kw_args)source

Enables the mail stub.

The email service stub is only available in dev_appserver because it uses thesubprocess module.

Parameters

  • enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

  • **stub_kw_args – Keyword arguments that are passed on to the service stub.

init_memcache_stub(enable=True)source

Enables the memcache stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_modules_stub(enable=True)source

Enables the modules stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_search_stub(enable=True)source

Enables the search stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

init_taskqueue_stub(enable=True, **stub_kw_args)source

Enables the taskqueue stub.

Parameters

  • enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

  • **stub_kw_args – Keyword arguments passed on to the service stub.

init_urlfetch_stub(enable=True, urlmatchers=None)source

Enables the urlfetch stub.

The urlfetch service stub uses the urllib module to make requests. On appserver, urllib also relies the urlfetch infrastructure, so using this stub will have no effect.

Parameters

  • enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

  • urlmatchers – optional initial sequence of (matcher, fetcher) pairs to populate urlmatchers_to_fetch_functions; matchers passed here, if any, take precedence over default matchers dispatching GCS access.

init_user_stub(enable=True, **stub_kw_args)source

Enables the users stub.

Parameters

  • enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

  • **stub_kw_args – Keyword arguments that are passed on to the service stub.

init_xmpp_stub(enable=True)source

Enables the xmpp stub.

Parameters

enable –True if the fake service should be enabled, orFalse if the real service should be disabled.

setup_env(overwrite=False, **kwargs)source

Sets default and custom environment variables.

By default, all of the items inDEFAULT_ENVIRONMENT will be created without being specified. To set a value other than the default, or to pass a custom environment variable, pass a corresponding keyword argument.

Example:

# All defaultstestbed_instance.setup_env()# All defaults, overriding AUTH_DOMAINtestbed_instance.setup_env(auth_domain='custom')# All defaults; adds a custom os.environ['CUSTOM'] = 'foo'testbed_instance.setup_env(custom='foo')

To overwrite the values set by a previous invocation, passoverwrite=True. Passing this value will not result in anOVERWRITE entry inos.environ.

Parameters

  • overwrite – Boolean; specifies whether to overwrite items with corresponding entries inos.environ.

  • **kwargs – Environment variables to set. The name of the argument will be uppercased and used as a key inos.environ.

google.appengine.ext.testbed.urlfetch_to_gcs_stub(url, payload, method, headers, request, response, follow_redirects=False, deadline=None, validate_certificate=None, http_proxy=None)source

Forwards Google Cloud Storageurlfetch requests to gcs_dispatcher.

google.appengine.ext.testbed.urlmatcher_for_gcs_stub(url)source

Determines whether a URL should be handled by the Cloud Storage stub.

Sub Modules

google.appengine.ext.testbed.apiserver_util

Utility class for testbed only used for py_test.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-06-16 UTC.