Modul:Mock title

Dokumentacija modula

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.

Usage

Loading the module

Load the module using require:

local mMockTitle = require('Module:Mock title')

Registering titles to mock

You can register a title to be mocked with the registerMockTitle function.

mMockTitle.registerMockTitle({title = "Main Page", isRedirect = true, redirectTarget = "Wikipedia:Village stocks"})

Or you can register multiple titles at once using registerMockTitles.

mMockTitle.registerMockTitles(
	{title = "File:Example.png", height = 250, width = 200},
	{title = "Template:3x", editProtection = "templateeditor"}
)

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

mMockTitle.registerMockCurrentTitle({title = "User:Example"})

Patching title constructors

During tests, you can use the patchTitleConstructors 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 patchTitleConstructors 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.

local function logCurrentTitle()
	mw.log(mw.title.getCurrentTitle().prefixedText)
end

logCurrentTitle() -- Logs "Module:Mock title"
mMockTitle.patchTitleConstructors(logCurrentTitle) -- Logs "User:Example"
logCurrentTitle() -- Logs "Module:Mock title"

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:

local mPageType = require('Module:Pagetype')
local ScribuntoUnit = require('Module:ScribuntoUnit')
local mMockTitle = require('Module:Mock title')
local suite = ScribuntoUnit:new()

mMockTitle.registerMockTitles(
	{title = 'United Kingdom', isRedirect = false},
	{title = 'UK', isRedirect = true}
)

function suite:testMainspacePages()
	local actual = mMockTitle.patchTitleConstructors(mPageType.main, {page = 'United Kingdom'})
	suite:assertEquals('article', actual)
end

function suite:testMainspaceRedirects()
	local actual = mMockTitle.patchTitleConstructors(mPageType.main, {page = 'UK'})
	suite:assertEquals('redirect', actual)
end

return suite

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 mPageType.main in the actual variable and compare it with the expected result outside of the patched function.

API documentation

Mock title constructors

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:

mMockTitle.MockTitle(options)

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 MockTitle, 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 pages 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.

local protectedFileMock = mMockTitle.MockTitle{
	title = "File:Example.png",
	editProtection = "sysop",
	moveProtection = "sysop",
}

Example 2: create a mock circular redirect.

local circularRedirectMock = mMockTitle.MockTitle{
	title = "Original page",
	isRedirect = true,
	redirectTarget = {
		title = "Redirect target",
		isRedirect = true,
		redirectTarget = "Original page",
	},
}

patchTitleObject

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

Usage:

mMockTitle.patchTitleObject(title, options)

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 title option is not required, and is ignored if specified.

Example: patch a title object for the Main Page.

local title = mw.title.new('Main Page')
local mock = mMockTitle.patchTitleObject(title, {content = "Mock content"})
mw.log(mock:getContent()) -- logs "Mock content"

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:

mMockTitle.registerMockTitle(titleOrOptions)

Parameters:

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

registerMockTitles

Register multiple mock titles.

Usage:

mMockTitle.registerMockTitles(...)

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:

mMockTitle.registerMockCurrentTitle(titleOrOptions)

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.

mMockTitle.deregisterMockTitle(titleOrOptions)

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:

mMockTitle.deregisterMockTitles(...)

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.

mMockTitle.deregisterMockCurrentTitle()

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.

mMockTitle.clearMockTitleRegistry()

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.

mMockTitle.clearMockTitleRegistry()

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.

mMockTitle.patchTitleNew(func, ...)

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.

mMockTitle.patchTitleNew(func, ...)

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.

mMockTitle.patchTitleNew(func, ...)

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.

mMockTitle.patchTitleNew(func, ...)

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.

require('strict')
local libraryUtil = require('libraryUtil')
local checkType = libraryUtil.checkType
local checkTypeMulti = libraryUtil.checkTypeMulti
local mRepr = require('Modul:Repr')

local p = {}
local mockTitleRegistry = {}
local mockCurrentTitle = nil

-- Keep a reference to the original mw.title.new function so that we can use it
-- when mw.title.new is patched with our custom function.
local titleNew = mw.title.new

--[[
-- Capitalize a string.
--]]
local function capitalize(s)
	return s:sub(1, 1):upper() .. s:sub(2, -1)
end

--[[
-- Check that a named argument is one of multiple types.
--]]
local function checkTypeForNamedArgMulti(name, argName, arg, expectTypes)
	local argType = type(arg)
	for _, expectedType in ipairs(expectTypes) do
		if argType == expectedType then
			return
		end
	end
	error(
		string.format(
			"bad named argument %s to '%s' (%s expected, got %s)",
			argName,
			name,
			mw.text.listToText(expectTypes, ', ', ' or '),
			argType
		),
		3
	)
end

--[[
-- Set a property on an object to the given value, if that value is not nil.
--]]
local function maybeSetProperty(object, property, value)
	if value ~= nil then
		rawset(object, property, value)
	end
end

--[[
-- Construct a mock title from a string, an ID or an options table. If we were
-- passed a mock title object to start with, return it as-is.
--]]
local function constructMockTitle(titleOrOptions)
	if titleOrOptions == nil then
		return nil
	end
	local titleOrOptionsType = type(titleOrOptions)
	if titleOrOptionsType == 'string' or titleOrOptionsType == 'number' then
		return p.MockTitle{title = titleOrOptions}
	elseif titleOrOptionsType == 'table' then
		if type(titleOrOptions.getContent) == 'function' then
			return titleOrOptions
		else
			return p.MockTitle(titleOrOptions)
		end
	else
		error(
			string.format(
				'Invalid type specified to constructMockTitle (expected string, number, table or nil; received %s)',
				titleOrOptionsType
			),
			2
		)
	end
end

--[[
-- Get a table of protection levels with the levels set by the user. The
-- makeOptionsKey is a function that takes a protection action as an input and
-- gives the option table key for that action. The function returns two values:
-- the table of protection levels (as used by the protectionLevels and
-- cascadingProtection title object properties), and a boolean flag indicating
-- whether any protection levels were set.
--]]
local function getProtectionLevels(options, makeOptionsKey)
	local levels = {
		edit = {},
		move = {},
		create = {},
		upload = {},
	}
	local isSet = false
	for action in pairs(levels) do
		local level = options[makeOptionsKey(action)]
		if level then
			levels[action][1] = level
			isSet = true
		end
	end
	return levels, isSet
end

--[[
-- Set protection levels
--]]
local function setProtectionLevels(title, options)
	local protectionLevels, isProtectionSet = getProtectionLevels(
		options,
		function (action)
			return action .. 'Protection'
		end
	)
	if isProtectionSet then
		rawset(title, 'protectionLevels', protectionLevels)
	end
end

--[[
-- Set cascading protection
--]]
local function setCascadingProtection(title, options)
	local cascadingProtectionLevels, isCascadingProtectionSet = getProtectionLevels(
		options,
		function (action)
			return string.format('cascading%sProtection', capitalize(action))
		end
	)
	local cascadingSourcesExist = options.cascadingProtectionSources and #options.cascadingProtectionSources >= 1
	if isCascadingProtectionSet and cascadingSourcesExist then
		rawset(
			title,
			'cascadingProtection',
			{
				restrictions = cascadingProtectionLevels,
				sources = options.cascadingProtectionSources,
			}
		)
	elseif isCascadingProtectionSet then
		error('a cascading protection argument was given but the cascadingProtectionSources argument was missing or empty', 2)
	elseif cascadingSourcesExist then
		error('the cascadingProtectionSources argument was given, but no cascading protection argument was given', 2)
	end
end

--[[
-- Set page content, if specified
--]]
local function maybeSetContent(titleObject, content)
	if content then
		rawset(titleObject, 'getContent', function () return content end)
	end
end

--[[
-- Set properties in the file table, as well as the fileExists property
--]]
local function setFileProperties(title, options)
	if title.file then
		for _, property in ipairs{'exists', 'width', 'height', 'pages', 'size', 'mimeType', 'length'} do
			local optionName = 'file' .. capitalize(property)
			maybeSetProperty(title.file, property, options[optionName])
		end
	end
end

--[[
-- Changes the associated titles to be patched if applicable
--]]
local function patchAssociatedTitleObjects(title)
	for _, property in ipairs{'basePageTitle', 'rootPageTitle', 'talkPageTitle', 'subjectPageTitle'} do
		local mockTitle = mockTitleRegistry[title[property] and title[property].prefixedText]
		if mockTitle then
			rawset(title, property, mockTitle)
		end
	end
	rawset(title, 'subPageTitle', function(text)
		return mw.title.makeTitle( title.namespace, title.text .. '/' .. text )
	end)
end

--[[
-- Patch an existing title object with the given options.
--]]
function p.patchTitleObject(title, options)
	checkType('patchTitleObject', 1, title, 'table')
	checkType('patchTitleObject', 2, options, 'table')
	
	-- Set simple properties
	for _, property in ipairs{'id', 'isRedirect', 'exists', 'contentModel'} do
		maybeSetProperty(title, property, options[property])
	end
	
	-- Set redirect title
	maybeSetProperty(title, 'redirectTarget', constructMockTitle(options.redirectTarget))
	
	-- Set complex properties
	setProtectionLevels(title, options)
	setCascadingProtection(title, options)
	maybeSetContent(title, options.content)
	setFileProperties(title, options)
	
	return title
end

--[[
-- Construct a new mock title.
--]]
function p.MockTitle(options)
	checkType('MockTitle', 1, options, 'table')
	checkTypeForNamedArgMulti('MockTitle', 'title', options.title, {'string', 'number'})
	-- Create the title object with the original mw.title.new so that we don't
	-- look in the mock title registry here when mw.title.new is patched.
	local title = titleNew(options.title)
	return p.patchTitleObject(title, options)
end

--[[
-- Register a mock title.
-- This can be a mock title object or a table of options for MockTitle.
--]]
function p.registerMockTitle(titleOrOptions)
	checkType('registerMockTitle', 1, titleOrOptions, 'table')
	local title = constructMockTitle(titleOrOptions)
	mockTitleRegistry[title.prefixedText] = title
end

--[[
-- Remove a title from the mock title registry.
-- Returns the title that was removed.
--]]
function p.deregisterMockTitle(titleOrOptions)
	checkTypeMulti('deregisterMockTitle', 1, titleOrOptions, {'number', 'string', 'table'})
	local title = constructMockTitle(titleOrOptions)
	if not title then
		return nil
	end
	local registeredTitle = mockTitleRegistry[title.prefixedText]
	mockTitleRegistry[title.prefixedText] = nil
	return registeredTitle
end

--[[
-- Register multiple mock titles.
--]]
function p.registerMockTitles(...)
	for i, titleOrOptions in ipairs{...} do
		checkType('registerMockTitles', i, titleOrOptions, 'table')
		p.registerMockTitle(titleOrOptions)
	end
end

--[[
-- Deregister multiple mock titles.
-- Returns a sequence of titles that were removed.
--]]
function p.deregisterMockTitles(...)
	local removedTitles = {}
	for i, titleOrOptions in ipairs{...} do
		checkTypeMulti('deregisterMockTitles', i, titleOrOptions, {'number', 'string', 'table'})
		table.insert(removedTitles, p.deregisterMockTitle(titleOrOptions))
	end
	return removedTitles
end

--[[
-- Clear the mock title registry.
--]]
function p.clearMockTitleRegistry()
	mockTitleRegistry = {}
end

--[[
-- Register a mock title as the current title.
-- This can be a string, a mock title object or a table of options for
-- MockTitle.
--]]
function p.registerMockCurrentTitle(titleOrOptions)
	checkType('registerMockCurrentTitle', 1, titleOrOptions, 'table')
	local title = constructMockTitle(titleOrOptions)
	mockCurrentTitle = title
end

--[[
-- Deregister the registered current mock title.
--]]
function p.deregisterMockCurrentTitle()
	mockCurrentTitle = nil
end

--[[
-- Clear all registered mock titles.
-- This clears the mock title registry and deregisters the current mock title.
--]]
function p.clearAllMockTitles()
	p.clearMockTitleRegistry()
	p.deregisterMockCurrentTitle()
end

--[[
-- Look up a title in the mock title registry.
--]]
local function lookUpTitleInRegistry(title)
	return mockTitleRegistry[title.prefixedText]
end

--[[
-- Look up the registered mock current title.
--]]
local function lookUpMockCurrentTitle()
	return mockCurrentTitle
end

--[[
-- Patch the given title function.
-- This replaces the title function with a function that looks up the title
-- from some source. Exactly how the title is looked up is determined by the
-- lookUpMockTitle argument. This should be a function that takes a title object
-- as input and returns a mock title object as output.
--]]
local function patchTitleFunc(funcName, lookUpMockTitle)
	local oldFunc = mw.title[funcName]
	mw.title[funcName] = function(...)
		local title = oldFunc(...)
		if not title then
			error(
				string.format(
					'Could not make title object from invocation %s',
					mRepr.invocationRepr{
						funcName = 'mw.title.' .. funcName,
						args = {...}
					}
				),
				2
			)
		end
		local mockTitle = lookUpMockTitle(title)
		-- This type of patching has to be applied to all titles and after all
		-- mocks are defined to ensure it works
		if mockTitle then
			patchAssociatedTitleObjects(mockTitle)
			return mockTitle
		else
			patchAssociatedTitleObjects(title)
			return title
		end
	end
	return oldFunc
end

--[[
-- Handle the patch process.
-- This takes care of setting up before the patch, running the specified
-- function after the patch, tearing down the patch, and returning the results.
-- The setup process is handled using the setup function, which takes no
-- parameters. Teardown is handled by the teardown function, which takes the
-- values returned by the setup function as input. The user-supplied function
-- is passed in as the func argument, which takes the remaining parameters as
-- arguments.
--]]
local function patch(setup, teardown, func, ...)
	local setupResults = {setup()}
	local results = {pcall(func, ...)}
	local success = table.remove(results, 1)
	teardown(unpack(setupResults))
	if success then
		return unpack(results)
	else
		error(results[1], 3)
	end
end

--[[
-- Patch mw.title.new.
-- The original mw.title.new is restored after running the given function.
--]]
function p.patchTitleNew(func, ...)
	checkType('patchTitleNew', 1, func, 'function')

	local function setup()
		return patchTitleFunc('new', lookUpTitleInRegistry)
	end
	
	local function teardown(oldTitleNew)
		mw.title.new = oldTitleNew
	end
	
	return patch(
		setup,
		teardown,
		func,
		...
	)
end

--[[
-- Patch mw.title.makeTitle.
-- The original mw.title.makeTitle is restored after running the given function.
--]]
function p.patchMakeTitle(func, ...)
	checkType('patchMakeTitle', 1, func, 'function')

	local function setup()
		return patchTitleFunc('makeTitle', lookUpTitleInRegistry)
	end
	
	local function teardown(oldMakeTitle)
		mw.title.makeTitle = oldMakeTitle
	end
	
	return patch(
		setup,
		teardown,
		func,
		...
	)
end

--[[
-- Patch mw.title.getCurrentTitle.
-- The original mw.title.getCurrentTitle is restored after running the given
-- function.
--]]
function p.patchGetCurrentTitle(func, ...)
	checkType('patchGetCurrentTitle', 1, func, 'function')

	local function setup()
		return patchTitleFunc('getCurrentTitle', lookUpMockCurrentTitle)
	end
	
	local function teardown(oldGetCurrentTitle)
		mw.title.getCurrentTitle = oldGetCurrentTitle
	end
	
	return patch(
		setup,
		teardown,
		func,
		...
	)
end

--[[
-- Patch mw.title.new, mw.title.makeTitle and mw.title.getCurrentTitle.
-- The original title functions are restored after running the given function.
--]]
function p.patchTitleConstructors(func, ...)
	checkType('patchTitleConstructors', 1, func, 'function')

	local function setup()
		local oldTitleNew = patchTitleFunc('new', lookUpTitleInRegistry)
		local oldMakeTitle = patchTitleFunc('makeTitle', lookUpTitleInRegistry)
		local oldGetCurrentTitle = patchTitleFunc('getCurrentTitle', lookUpMockCurrentTitle)
		return oldTitleNew, oldMakeTitle, oldGetCurrentTitle
	end
	
	local function teardown(oldTitleNew, oldMakeTitle, oldGetCurrentTitle)
		mw.title.new = oldTitleNew
		mw.title.makeTitle = oldMakeTitle
		mw.title.getCurrentTitle = oldGetCurrentTitle
	end
	
	return patch(
		setup,
		teardown,
		func,
		...
	)
end

return p