Module:Mock title/doc

This module allows you to easily mock Scribunto title objects. This can be useful when writing unit tests for modules which depend on whether a certain page exists, or whether a certain page is a redirect, etc. If you don't use mock title objects, then you run the risk of some editor changing a page that your test cases relied on (e.g. redirecting it or deleting it), thus breaking your tests. By using mock objects, you get to specify things like existence status and redirect status in your tests, making them more resilient against changes to real pages.

Loading the module
Load the module using :

Registering titles to mock
You can register a title to be mocked with the  function.

Or you can register multiple titles at once using.

You can also register a mock for the current page with.

Patching title constructors
During tests, you can use the  function to temporarily replace the title constructors mw.title.new, mw.title.makeTitle and mw.title.getCurrentTitle with functions that return the mock titles that you registered. You pass  your own function containing your test code; while the function is running the title constructors will return mock titles, but after it finishes running they will be restored to their original versions.

Sample test code
Let's say you want to test Module:Pagetype. This module displays a page type such as "article" for pages in mainspace, and "file" for pages in the File namespace. It also displays "redirect" for redirects in any namespace. Because of its ability to detect redirects, the module's output depends on the content of pages on the wiki. If we just used regular pages, then this would mean that people could break our tests just by redirecting certain pages. Not good!

To protect against this eventuality, we can use mock titles.

This example uses Module:ScribuntoUnit as the test runner. The /testcases module would include code like this:

Note that in these tests we make use of patchTitleConstructors' ability to return the value of the function it runs. This means that we can store the result of  in the   variable and compare it with the expected result outside of the patched function.

MockTitle
Creates a mock title object.

Mock title objects function like normal title objects, but values you specify when creating them are used instead of the real values taken from the wiki.

Usage:

Parameters:

This function takes a table of options. The possible options are as follows:


 * title - the page title. If this is a string, it is the page title as used with mw.title.new. If it is a number, it is the page ID. (required)
 * id - the page ID. (int, optional)
 * contentModel - the content model. (string, optional)
 * exists - whether the page exists. (bool, optional)
 * isRedirect - whether the page is a redirect. (bool, optional)
 * redirectTarget - the redirect target of the page. This can be a string (the page title as used with mw.title.new), a number (the page ID), a table of options for, or a title object (mock or otherwise).
 * content - the page's content. (string, optional)
 * editProtection - the edit protection level, e.g. "sysop" or "editsemiprotected". (string, optional)
 * moveProtection - the move protection level, e.g. "sysop" or "extendedconfirmed". (string, optional)
 * createProtection - the create protection level, e.g. "sysop". (string, optional)
 * uploadProtection - the upload protection level, e.g. "sysop". (string, optional)
 * cascadingEditProtection - the edit protection level for cascading protection, e.g. "sysop" or "editsemiprotected". (string, optional)
 * cascadingMoveProtection - the move protection level for cascading protection, e.g. "sysop" or "extendedconfirmed". (string, optional)
 * cascadingCreateProtection - the create protection level for cascading protection, e.g. "sysop". (string, optional)
 * cascadingUploadProtection - the upload protection level for cascading protection, e.g. "sysop". (string, optional)
 * fileExists - whether the file exists (not used for non-file titles). (bool, optional)
 * fileWidth - the file width in pixels (not used for non-file titles). (int, optional)
 * fileHeight - the file height in pixels (not used for non-file titles). (int, optional)
 * filePages - pages in the file (not used for non-file titles). See the Scribunto documentation of the title object  parameter for the correct format. (table, optional)
 * fileSize - the file size in bytes (not used for non-file titles). (int, optional)
 * fileMimeType - the MIME type of the file (not used for non-file titles). (int, optional)
 * fileLength - the file length (duration) in seconds (not used for non-file titles). (int, optional)

Example 1: create a mock title of a fully protected file.

Example 2: create a mock circular redirect.

patchTitleObject
Create a mock title object by patching an existing title object with the specified options.

Usage:

Parameters:

This function takes two parameters:


 * title - the title object to patch. (table, required)
 * options - options specifying data in the title object to be mocked (table, required). The possible options are the same as for MockTitle, except that the  option is not required, and is ignored if specified.

Example: patch a title object for the Main Page.

Registration functions
These functions allow you to register mock titles in the module's internal mock title registry. When title constructors are patched with one of the patching functions, the title constructors return mock titles registered with these functions instead of normal title objects.

registerMockTitle
Register a single mock title.

Usage:

Parameters:


 * titleOrOptions - a MockTitle object, or a table of MockTitle object options. (table, required)

registerMockTitles
Register multiple mock titles.

Usage:

Parameters:

This function takes a variable number of parameters, each of which must be either a MockTitle object, or a table of MockTitle object options. (table, required)

registerMockCurrentTitle
Register a mock title as the current title. If mw.title.getCurrentTitle is patched with a patching function, it will return the mock title registered with this function.

Usage:

Parameters:


 * titleOrOptions - a MockTitle object, or a table of MockTitle object options. (table, required)

Deregistration functions
These functions remove mock titles registered with one of the registration functions.

deregisterMockTitle
Remove a single title from the mock title registry.

Parameters:


 * titleOrOptions - the title to be removed (required). Must be one of the following:
 * A page name (string)
 * A page ID (number)
 * A MockTitle object (table)
 * A table of MockTitle object options (table)

deregisterMockTitles
Remove multiple titles from the mock title registry.

Usage:

Parameters:

This function takes a variable number of parameters, each of which must be one of the following:
 * A page name (string)
 * A page ID (number)
 * A MockTitle object (table)
 * A table of MockTitle object options (table)

deregisterMockCurrentTitle
Remove the mock title registered as the current title.

clearMockTitleRegistry
Remove all titles from the mock title registry. This removes titles added with registerMockTitle or registerMockTitles, but does not remove the registered mock current title.

clearAllMockTitles
Remove all mock titles. This removes titles from the mock title registry that were added with registerMockTitle or registerMockTitles, and also removes the registered mock current title.

Patching functions
These functions patch one or more of the Scribunto functions that create title objects. When these functions are patched, the patched versions will return mock titles registered with one of the registration functions.

patchTitleNew
Patch mw.title.new.

Parameters:
 * func: a function to be run while mw.title.new is patched. The original mw.title.new will be restored after the function is run.
 * Other positional parameters: arguments to be passed to the func parameter.

Returns: the result of the func parameter.

patchMakeTitle
Patch mw.title.makeTitle.

Parameters:
 * func: a function to be run while mw.title.makeTitle is patched. The original mw.title.makeTitle will be restored after the function is run.
 * Other positional parameters: arguments to be passed to the func parameter.

Returns: the result of the func parameter.

patchGetCurrentTitle
Patch mw.title.getCurrentTitle.

Parameters:
 * func: a function to be run while mw.title.getCurrentTitle is patched. The original mw.title.getCurrentTitle will be restored after the function is run.
 * Other positional parameters: arguments to be passed to the func parameter.

Returns: the result of the func parameter.

patchTitleConstructors
Patch all title constructors: mw.title.new, mw.title.makeTitle, and mw.title.getCurrentTitle.

Parameters:
 * func: a function to be run while the title constructors are patched. The original title constructors will be restored after the function is run.
 * Other positional parameters: arguments to be passed to the func parameter.

Returns: the result of the func parameter.