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:

import unittest

from google.appengine.ext import ndb
from google.appengine.ext import testbed


class TestModel(ndb.Model):
  number = ndb.IntegerProperty(default=42)


class MyTestCase(unittest.TestCase):

  def setUp(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()

  def tearDown(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()

  def testInsertEntity(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, call self.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, call self.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 uses os.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 with self.setup_env().

class google.appengine.ext.testbed.EmulatorSupportCheckersource

Bases: object

A static class. Checks whether datastore emulator is supported.

classmethod check()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.

classmethod get_api_port()source

Returns the integer port number that api_server listens on.

classmethod get_emulator_port()source

Returns the integer port number that datastore emulator listens on.

classmethod init(api_port, emulator_port)source
exception google.appengine.ext.testbed.Errorsource

Bases: exceptions.Exception

Base testbed error type.

exception google.appengine.ext.testbed.NotActivatedErrorsource

Bases: google.appengine.ext.testbed.Error

Raised if the used testbed instance is not activated.

exception google.appengine.ext.testbed.StubNotSupportedErrorsource

Bases: google.appengine.ext.testbed.Error

Raised if an unsupported service stub is accessed.

class google.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 corresponding init_*_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 as os.environ[‘APPLICATION_ID’]. You can set custom values with setup_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 before activate() was called.

Raises

NotActivatedError – If called before activate() was called.

get_stub(service_name)source

Gets the stub for a service.

Parameters

service_name – The name of the service.

Returns

The stub for service_name.

Raises
init_all_stubs(enable=True)source

Enables all known testbed stubs.

Parameters

enable – True if the fake service should be enabled, or False 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, or False 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, or False 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, or False 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, or False 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.

The datastore_file argument can be set to the path of an existing datastore file, or None (default) to use an in-memory datastore that is initially empty. If you use the sqlite stub and have defined datastore_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 set save_changes=True.

Parameters

  • enable – True if the fake service should be enabled, or False 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, or False (default) to use the file stub.

  • auto_id_policy – How datastore stub assigns auto IDs. This value can be either AUTO_ID_POLICY_SEQUENTIAL or AUTO_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, or False 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, or False 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, or False 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 the subprocess module.

Parameters

  • enable – True if the fake service should be enabled, or False 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, or False 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, or False 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, or False 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, or False 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, or False 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, or False 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, or False 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 in DEFAULT_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 defaults
testbed_instance.setup_env()
# All defaults, overriding AUTH_DOMAIN
testbed_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, pass overwrite=True. Passing this value will not result in an OVERWRITE entry in os.environ.

Parameters

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

  • **kwargs – Environment variables to set. The name of the argument will be uppercased and used as a key in os.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 Storage urlfetch 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.