tests.aspects module

Test aspects to allow fine grained control over what tests are executed.

Several parts of the test infrastructure are implemented as mixins, such as API result caching and excessive test durations.

class tests.aspects.AlteredDefaultSiteTestCase(*args, **kwargs)

Bases: TestCase

Save and restore the config.mylang and config.family.

abstract_class = True

setUp()

Prepare the environment for running main() in a script.

Return type:

None

tearDown()

Restore the environment.

Return type:

None

class tests.aspects.CheckHostnameMixin(methodName='runTest')

Bases: TestCaseBase

Check the hostname is online before running tests.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

classmethod setUpClass()

Set up the test class.

Prevent tests running if the host is down.

Return type:

None

class tests.aspects.DefaultDrySiteTestCase(*args, **kwargs)

Bases: DefaultSiteTestCase

Run tests using the config specified site in offline mode.

abstract_class = True

dry = True

class tests.aspects.DefaultSiteTestCase(*args, **kwargs)

Bases: TestCase

Run tests against the config specified site.

abstract_class = True

code = 'test'

family = 'wikipedia'

classmethod override_default_site(site)

Override the default site.

Parameters:

site (BaseSite) – site tests should use

Return type:

None

class tests.aspects.DefaultWikibaseClientTestCase(*args, **kwargs)

Bases: WikibaseClientTestCase, DefaultSiteTestCase

Run tests against any site connected to a Wikibase.

abstract_class = True

class tests.aspects.DefaultWikidataClientTestCase(*args, **kwargs)

Bases: DefaultWikibaseClientTestCase

Run tests against any site connected to Wikidata.

abstract_class = True

classmethod setUpClass()

Set up the test class.

Require the data repository is wikidata.org.

Return type:

None

class tests.aspects.DeprecationTestCase(*args, **kwargs)

Bases: TestCase

Test cases for deprecation function in the tools module.

INSTEAD = <object object>

NO_INSTEAD = <object object>

abstract_class = True

assertDeprecation(msg=None)

Assert that a deprecation warning happened.

Parameters:

msg (str or None or INSTEAD or NO_INSTEAD) – Either the specific message or None to allow any generic message. When set to INSTEAD it only counts those supplying an alternative and when NO_INSTEAD only those not supplying one.

Return type:

None

assertDeprecationClass(cls)

Assert that all deprecation warning are of one class.

Return type:

None

assertDeprecationFile(filename)

Assert that all deprecation warning are of one filename.

Return type:

None

assertDeprecationParts(deprecated=None, instead=None)

Assert that a deprecation warning happened.

To simplify deprecation tests it just requires the to separated parts and forwards the result to assertDeprecation.

Parameters:

• deprecated (str or None) – The deprecated string. If None it uses a generic match depending on instead.

• instead (str or None or True or False) – The instead string unless deprecated is None. If it’s None it allows any generic deprecation string, on True only those where instead string is present and on False only those where it’s missing. If the deprecation string is not None, no instead string is expected when instead evaluates to False.

Return type:

None

assertNoDeprecation(msg=None)

Assert that no deprecation warning happened.

Return type:

None

assertOneDeprecation(msg=None, count=1)

Assert that exactly one deprecation message happened and reset.

Return type:

None

assertOneDeprecationParts(deprecated=None, instead=None, count=1)

Assert that exactly one deprecation message happened and reset.

It uses the same arguments as assertDeprecationParts.

Return type:

None

property deprecation_messages

Return captured deprecation warnings.

setUp()

Set up unit test.

Return type:

None

classmethod setUpClass()

Only operate in debug mode.

Return type:

None

source_adjustment_skips = [<class 'unittest.case._AssertRaisesBaseContext'>, <class 'unittest.case._AssertRaisesContext'>, <function TestCase.assertRaises>, <function TestCase.assertRaisesRegex>]

tearDown()

Tear down unit test.

Return type:

None

class tests.aspects.DisableSiteMixin(methodName='runTest')

Bases: TestCaseBase

Test cases not connected to a Site object.

Do not use this for mock Site objects.

Never set a class or instance variable called ‘site’ As it will prevent tests from executing when invoked as: $ pytest -a ‘not site’

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()

Set up test.

Return type:

None

tearDown()

Tear down test.

Return type:

None

class tests.aspects.DisconnectedSiteMixin(methodName='runTest')

Bases: TestCaseBase

Test cases using a disconnected Site object.

Do not use this for mock Site objects.

Never set a class or instance variable called ‘site’ As it will prevent tests from executing when invoked as: $ pytest -a ‘not site’

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()

Set up test.

Return type:

None

tearDown()

Tear down test.

Return type:

None

class tests.aspects.ForceCacheMixin(methodName='runTest')

Bases: TestCaseBase

Aggressively cached API test cases.

Patches pywikibot.data.api to aggressively cache API responses.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()

Set up test.

Return type:

None

tearDown()

Tear down test.

Return type:

None

class tests.aspects.HttpbinTestCase(*args, **kwargs)

Bases: TestCase

Custom test case class, which allows dry httpbin tests.

Test cases, which use httpbin, need to inherit this class.

abstract_class = True

fetch(*args, **kwargs)

Delegate http request to http.fetch but skip on ServerError.

get_httpbin_hostname()

Return httpbin hostname.

Return type:

str

get_httpbin_url(path='')

Return url of httpbin.

sites = {'httpbin': {'hostname': 'httpbin.org'}}

class tests.aspects.MetaTestCaseClass(name, bases, dct)

Bases: type

Test meta class.

Create the new class.

Changed in version 9.3: raises AttributeError instead of AssertionError for duplicated hostname, raises Exception instead of AssertionError for missing or wrong “net” attribute with hostnames.

Raises:

• AttributeError – hostname already found

• Exception – Test classes using “pwb” must set “site” or test classes without a “site” configured must set “net” or test method must accept either 1 or 2 arguments or “net” must be True with hostnames defined.

static add_base(bases, subclass)

Return a tuple of bases with the subclasses added if not already.

static add_method(dct, test_name, method, doc=None, doc_suffix=None)

Set method’s __name__ and __doc__ and add it to dct.

Changed in version 9.3: raises ValueError instead of AssertionError

Raises:

ValueError – doc string must end with a period.

Return type:

None

class tests.aspects.NeedRightsMixin(methodName='runTest')

Bases: TestCaseBase

Require specific rights.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

classmethod setUpClass()

Set up the test class.

Skip the test class if the user does not have required rights.

Return type:

None

class tests.aspects.PatchingTestCase(*args, **kwargs)

Bases: TestCase

Easily patch and unpatch instances.

abstract_class = True

patch(obj, attr_name, replacement)

Patch the obj’s attribute with the replacement.

It will be reset after each tearDown.

Return type:

None

static patched(obj, attr_name)

Apply patching information.

setUp()

Set up the test by initializing the patched list.

Return type:

None

tearDown()

Tear down the test by unpatching the patched.

Return type:

None

class tests.aspects.PwbTestCase(*args, **kwargs)

Bases: TestCase

Test cases use pwb to invoke scripts.

Test cases which use pwb typically also access a site, and use the network. Even during initialisation, scripts may call pywikibot.handle_args(), which initialises loggers and uses the network to determine if the code is stale.

The flag ‘pwb’ is used by the TestCase metaclass to check that a test site is set declared in the class properties, or that site = False is added to the class properties in the unlikely scenario that the test case uses pwb in a way that doesn’t use a site.

If a test class is marked as site = False , the metaclass will also check that the ``net` flag is explicitly set.

abstract_class = True

execute(args, **kwargs)

Run tests.utils.execute_pwb() with default site.

Changed in version 9.1: pass all arguments to tests.utils.execute_pwb(); make this method public.

Parameters:

• args (list[str]) – pwb warapper script arguments

• kwargs – keyword arguments of tests.utils.execute_pwb()

pwb = True

setUp()

Prepare the environment for running the pwb.py script.

Return type:

None

tearDown()

Restore the environment after running the pwb.py script.

Return type:

None

class tests.aspects.Python314AssertionsMixin

Bases: object

Mixin providing assertion methods added in Python 3.14 for unittest.

This mixin ensures TestCase compatibility on older Python versions.

The mixin will be removed without deprecation period once Python 3.14 becomes the minimum requirement for Pywikibot, likely with Pywikibot 16.

Added in version 10.3.

assertEndsWith(s, suffix, msg=None)

Fail if the string s does not end with suffix.

Parameters:

• s (str) – The string to check.

• suffix (str) – The expected suffix.

• msg (str | None) – Optional custom failure message.

Return type:

None

assertHasAttr(obj, name, msg=None)

Fail if the object obj does not have an attribute name.

Parameters:

• obj (object) – The object to check.

• name (str) – The expected attribute name.

• msg (str | None) – Optional custom failure message.

Return type:

None

assertIsSubclass(cls, superclass, msg=None)

Fail if cls is not a subclass of superclass.

Parameters:

• cls (type) – The class to test.

• superclass (type | tuple[type, ...]) – The expected superclass or tuple of superclasses.

• msg (str | None) – Optional custom failure message.

Return type:

None

assertNotEndsWith(s, suffix, msg=None)

Fail if the string s ends with suffix.

Parameters:

• s (str) – The string to check.

• suffix (str) – The unwanted suffix.

• msg (str | None) – Optional custom failure message.

Return type:

None

assertNotHasAttr(obj, name, msg=None)

Fail if the object obj has an attribute name.

Parameters:

• obj (object) – The object to check.

• name (str) – The unwanted attribute name.

• msg (str | None) – Optional custom failure message.

Return type:

None

assertNotIsSubclass(cls, superclass, msg=None)

Fail if cls is a subclass of superclass.

Parameters:

• cls (type) – The class to test.

• superclass (type | tuple[type, ...]) – The superclass or tuple of superclasses to reject.

• msg (str | None) – Optional custom failure message.

Return type:

None

assertNotStartsWith(s, prefix, msg=None)

Fail if the string s starts with prefix.

Parameters:

• s (str) – The string to check.

• prefix (str) – The unwanted prefix.

• msg (str | None) – Optional custom failure message.

Return type:

None

assertStartsWith(s, prefix, msg=None)

Fail if the string s does not start with prefix.

Parameters:

• s (str) – The string to check.

• prefix (str) – The expected prefix.

• msg (str | None) – Optional custom failure message.

Return type:

None

class tests.aspects.RecentChangesTestCase(*args, **kwargs)

Bases: WikimediaDefaultSiteTestCase

Test cases for tests that use recent change.

abstract_class = True

length = 3

classmethod setUpClass()

Set up test class.

Return type:

None

class tests.aspects.RequireLoginMixin(methodName='runTest')

Bases: TestCaseBase

Run tests against a specific site, with a login.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

get_userpage(site=None)

Create a User object for the user’s userpage.

classmethod require_site_user(family, code)

Check the user config has a valid login to the site.

Return type:

None

setUp()

Set up the test case.

Login to the site if it is not logged in.

Return type:

None

classmethod setUpClass()

Set up the test class.

Skip the test class if the user config does not have a valid login to the site.

Return type:

None

tearDown()

Log back into the site.

Return type:

None

class tests.aspects.ScriptMainTestCase(*args, **kwargs)

Bases: AlteredDefaultSiteTestCase

Tests that depend on the default site being set to the test site.

abstract_class = True

setUp()

Prepare the environment for running main() in a script.

Return type:

None

class tests.aspects.SiteAttributeTestCase(*args, **kwargs)

Bases: TestCase

Add the sites as attributes to the instances.

abstract_class = True

classmethod setUpClass()

Add each initialized site as an attribute to cls.

Return type:

None

class tests.aspects.SiteNotPermitted(code, fam=None, user=None)

Bases: BaseSite

Site interface to prevent sites being loaded.

class tests.aspects.SiteWriteMixin(methodName='runTest')

Bases: TestCaseBase

Test cases involving writing to the server.

When editing, the API should not be patched to use CachedRequest. This class prevents that.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

classmethod setUpClass()

Set up the test class.

Reject write test classes configured with non-test wikis, or caching. Prevent test classes from writing to the site by default.

The test class is skipped unless environment variable PYWIKIBOT_TEST_WRITE is set to 1.

Changed in version 9.2: PYWIKIBOT_TEST_WRITE_FAIL environment variable was discarded, see Environment variables.

Raises:

Exception – test class cannot use write attribute together with cached and must be run on test sites only.

Return type:

None

class tests.aspects.TestCase(*args, **kwargs)

Bases: TestCaseBase

Run tests on pre-defined sites.

abstract_class = True

get_mainpage(site=None, force=False)

Create a Page object for the sites main page.

Parameters:

• site (pywikibot.site.APISite or None) – Override current site, obtained using get_site.

• force (bool) – Get an unused Page object

Return type:

Page

get_missing_article(site=None)

Get a Page which refers to a missing page on the site.

Return type:

Page

classmethod get_site(name=None)

Return the prefetched Site object.

Changed in version 9.3: raises Exception instead of AssertionError for site mismatch

Raises:

Exception – method called for multiple sites without name argument given or name not found in sites attribute or cls.site is not equal to cls.sites content for the given name.

classmethod has_site_user(family, code)

Check the user config has a user for the site.

classmethod setUpClass()

Set up the test class.

Prefetch the Site object for each of the sites the test class has declared are needed.

Return type:

None

class tests.aspects.TestCaseBase(methodName='runTest')

Bases: TestTimerMixin, Python314AssertionsMixin

Base class for all tests.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

_get_gen_pages(gen, site=None)

Get pages from gen, asserting they are Page from site.

Changed in version 9.3: the count parameter was dropped; all pages from gen are tested.

Parameters:

• gen (Iterable[Page]) – Page generator

• site (APISite | None) – Site of expected pages

Return type:

list[Page]

assertAPIError(code, info=None, callable_obj=None, *args, regex=None, **kwargs)

Assert that a specific APIError wrapped around assertRaises.

If no callable object is defined and it returns a context manager, that context manager will return the underlying context manager used by assertRaises. So it’s possible to access the APIError by using it’s exception attribute.

Parameters:

• code (str) – The code of the error which must have happened.

• info (str or None) – The info string of the error or None if no it shouldn’t be checked.

• callable_obj (callable) – The object that will be tested. If None it returns a context manager like assertRaises.

• args – The positional arguments forwarded to the callable object.

• kwargs – The keyword arguments forwarded to the callable object.

Returns:

Context manager if callable_obj is None and None otherwise.

Return type:

None or context manager

assertIsEmpty(seq, msg=None)

Check that the sequence is empty.

Return type:

None

assertIsNotEmpty(seq, msg=None)

Check that the sequence is not empty.

Return type:

None

assertLength(seq, other, msg=None)

Verify that a sequence seq has the length of other.

Return type:

None

assertPageInNamespaces(page, namespaces)

Assert that Pages is in namespaces.

Parameters:

• page (pywikibot.BasePage) – Page

• namespaces (int | set[int]) – expected namespaces

Return type:

None

assertPageTitlesCountEqual(gen, titles, site=None)

Test that pages in gen match expected titles, regardless of order.

Parameters:

• gen (Iterable[Page]) – Page generator

• titles (Iterator[str]) – Expected titles

• site (APISite | None) – Site of expected pages

Return type:

None

assertPageTitlesEqual(gen, titles, site=None)

Test that pages in gen match expected titles.

Parameters:

• gen (Iterable[Page]) – Page generator

• titles (Iterator[str]) – Expected titles

• site (APISite | None) – Site of expected pages

Return type:

None

assertPagesInNamespaces(gen, namespaces)

Assert that generator returns Pages all in namespaces.

Parameters:

• gen (generator) – generator to iterate

• namespaces (int | set[int]) – expected namespaces

Return type:

None

assertPagesInNamespacesAll(gen, namespaces, skip=False)

Try to confirm that generator returns Pages for all namespaces.

Changed in version 9.3: raises TypeError instead of AssertionError

Parameters:

• gen (generator) – generator to iterate

• namespaces (int | set[int]) – expected namespaces

• skip (bool) – skip test if not all namespaces found

Raises:

TypeError – Invalid namespaces type

Return type:

None

class tests.aspects.TestTimerMixin(methodName='runTest')

Bases: TestCase

Time each test and report excessive durations.

Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

setUp()

Set up test.

Return type:

None

tearDown()

Tear down test.

Return type:

None

test_duration_warning_interval = 10

class tests.aspects.WikibaseClientTestCase(*args, **kwargs)

Bases: WikibaseTestCase

Run tests against a specific site connected to a wikibase.

abstract_class = True

classmethod setUpClass()

Set up the test class.

Checks that all sites are configured as a Wikibase client, with Site.has_data_repository returning True.

Return type:

None

class tests.aspects.WikibaseTestCase(*args, **kwargs)

Bases: TestCase

Run tests against a wikibase site.

abstract_class = True

classmethod get_repo()

Return the prefetched DataSite object.

classmethod setUpClass()

Set up the test class.

Checks that all sites are configured with a Wikibase repository, with Site.has_data_repository() returning True, and all sites use the same data repository.

Return type:

None

wikibase = True

class tests.aspects.WikidataTestCase(*args, **kwargs)

Bases: WikibaseTestCase

Test cases use Wikidata.

abstract_class = True

cached = True

code = 'wikidata'

family = 'wikidata'

class tests.aspects.WikimediaDefaultSiteTestCase(*args, **kwargs)

Bases: DefaultSiteTestCase

Test class to run against a WMF site, preferring the default site.

abstract_class = True

classmethod setUpClass()

Set up the test class.

Check that the default site is a Wikimedia site. Use en.wikipedia.org as a fallback.

Changed in version 9.3: raises Exception instead of AssertionError

Raises:

Exception – “site” or “sites” attribute is missing or “sites” entries count is different from 1.

Return type:

None

tests.aspects.require_modules(*required_modules)

Require that the given list of modules can be imported.

tests.aspects.require_version(version_needed, /, reason='')

Skip test unless a minimum MediaWiki version is available.

The required version must include a comparison operator (e.g. <1.31wmf4 or >=1.43). If the site’s version does not satisfy the condition, the test is skipped.

This decorator can only be used for TestCase having a single site. It cannot be used for DrySite tests. Version checks are only supported for the current site — not for related sites like data or image repositories.

Added in version 8.0.

Changed in version 10.0: TypeError and ValueError are used for validation fails. version_needed parameter is positional only.

Parameters:

• version_needed (str) – The version needed

• reason (str) – A reason for skipping the test.

Raises:

• TypeError – self.site is not a BaseSite or the decorated method has parameters.

• ValueError – The given version_needed parameter is invalid or an operand is given on the left or the version number is invalid