path: root/pmstestsuite/library/case.py

#	vim:fileencoding=utf-8
# (c) 2011 Michał Górny <mgorny@gentoo.org>
# Released under the terms of the 2-clause BSD license.

import copy, random, re
from gentoopm.util import ABCObject

from abc import ABCMeta, abstractmethod, abstractproperty

# XXX: move to some consts module?
phase_func_names = [
	'pkg_pretend', 'pkg_setup', 'src_unpack', 'src_prepare',
	'src_configure', 'src_compile', 'src_install',
	'pkg_preinst', 'pkg_postinst'
]

""" Names of all phase functions supported in EAPIs. """

ebuild_header = '''# Copyright 1999-2011 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

EAPI=%d

inherit %s

'''

""" A common ebuild header. """

pn_re = re.compile('([^A-Z])([A-Z])')

def cleanup_test_case_name(classname):
	"""
	Create the ebuild PN from classname.

	>>> cleanup_test_case_name('Testzor')
	'testzor'
	>>> cleanup_test_case_name('TestzorTest')
	'testzor'
	>>> cleanup_test_case_name('TestZorTest')
	'test-zor'
	>>> cleanup_test_case_name('veryRandomCamelCaseTest')
	'very-random-camel-case'
	>>> cleanup_test_case_name('RDependTest')
	'rdepend'

	@param classname: the class name to clean up
	@type classname: string
	"""

	if classname.endswith('Test'):
		classname = classname[:-4]
	return pn_re.sub('\\1-\\2', classname).lower()

class TestCase(ABCObject):
	"""
	Base class for a test case.

	@ivar _finalized: has the case initialization been finished yet?
		Set by L{_finalize()}.
	@type _finalized: bool
	"""

	_finalized = False

	def _finalize(self):
		"""
		Do any final modifications to test case data. Mark it finalized.
		This function shall be called at most once per object.
		"""
		self._finalized = True

	@abstractmethod
	def get_output_files(self):
		"""
		Get a dict of files to output in the repository for the test case.

		@return: a dict where keys are file paths (relative to the repository
			root), and values evaluate to file contents
		@rtype: dict (string -> stringifiable)
		"""
		pass

	@abstractmethod
	def clean(self, pm):
		"""
		Schedule cleaning the test.

		@param pm: the package manager instance
		@type pm: L{PackageManager}
		"""
		pass

	@abstractmethod
	def start(self, pm):
		"""
		Schedule starting the test.

		@param pm: the package manager instance
		@type pm: L{PackageManager}
		"""
		pass

	@abstractmethod
	def check_result(self, pm):
		"""
		Check the correctness of the result of test execution.

		@param pm: the package manager instance
		@type pm: L{PackageManager}

		@return: True if the test succeeded, False otherwise
		@rtype: bool
		"""
		pass

class EbuildTestCase(TestCase):
	"""
	Test case using a single ebuild (per EAPI).

	The __init__() function is going to clone (deepcopy()) all the instance
	variables to allow modifying them easily.

	@ivar ebuild_vars: additional global variables
	@type ebuild_vars: dict (string -> string)
	@ivar expect_failure: if set to False (the default), the test is supposed
		to merge successfully. Otherwise, the test ebuild is supposed to fail
		to merge (die)
	@type expect_failure: bool
	@ivar inherits: additional eclasses to inherit
	@type inherits: list (string)
	@ivar phase_funcs: phase function contents
	@type phase_funcs: dict (string -> list(string))
	"""

	ebuild_vars = {}
	expect_failure = False
	inherits = []
	phase_funcs = {}

	@classmethod
	def _eval_prop(cls, prop_or_obj):
		"""
		Evaluate and return the value of a property when passed a property
		object, or return the passed value otherwise.

		@param prop_or_obj: the object to process
		@type prop_or_obj: property/object
		@return: value of the property
		@rtype: object
		"""

		if isinstance(prop_or_obj, property):
			return prop_or_obj.fget(cls)
		else:
			return prop_or_obj

	@property
	def supported_eapis(cls):
		"""
		A list of EAPIs for which the test is able to run and gives
		predictible results. Defaults to all available EAPIs.

		For example, if a feature is required in EAPI 3+ and optional
		in earlier EAPIs, this variable should contain (3,4).

		@type: iterable
		"""
		return (0, 1, 2, 3, 4)

	@property
	def relevant_eapis(cls):
		"""
		A list of EAPIs for which the test should be run by default (in
		non-thorough mode). This should list all the EAPIs where
		a change of behaviour occurs.

		When unset, defaults to a random element of .supported_eapis().

		@type: iterable
		"""
		return (random.choice(cls._eval_prop(cls.supported_eapis)),)

	@classmethod
	def inst_all(cls, thorough = False):
		"""
		Instantiate the test case for all relevant EAPIs. If in thorough
		mode, assume all supported EAPIs are relevant.

		@return: an iterable over test case instances
		@rtype: generator(L{EbuildTestCase})
		"""

		if thorough:
			eapis = cls.supported_eapis
		else:
			eapis = cls.relevant_eapis

		for eapi in cls._eval_prop(eapis):
			yield cls(eapi = eapi)

	@property
	def pn(self):
		return cleanup_test_case_name(self.__class__.__name__)

	@property
	def pv(self):
		return self.eapi

	@property
	def p(self):
		return '%s-%s' % (self.pn, self.pv)

	@property
	def cpv(self):
		""" Return CPV for the test. """
		return 'pms-test/%s' % self.p

	def atom(self, pm):
		""" Return atom for the test. """
		return pm.Atom('=%s' % self.cpv)

	@property
	def _stripped_docstring(self):
		descdoc = ' '.join(self.__doc__.split())
		return descdoc.rstrip('.')

	def _finalize(self):
		TestCase._finalize(self)

		if 'DESCRIPTION' not in self.ebuild_vars:
			self.ebuild_vars['DESCRIPTION'] = self._stripped_docstring

	def __str__(self):
		""" Return freetext test description. """
		return '%s (%s)' % (self.p, self._stripped_docstring)

	def __init__(self, eapi):
		"""
		Instiantate the test case for a particular EAPI.

		@param eapi: the EAPI
		@type eapi: string
		"""
		self.eapi = eapi

		for v in ('ebuild_vars', 'inherits', 'phase_funcs'):
			setattr(self, v, copy.deepcopy(getattr(self, v)))
		for pf in phase_func_names:
			if pf not in self.phase_funcs:
				self.phase_funcs[pf] = []

		# add KEYWORDS to the ebuild
		self.ebuild_vars['KEYWORDS'] = 'alpha amd64 arm hppa ia64 ' + \
				'm68k ~mips ppc ppc64 s390 sh sparc x86'

	def get_output_files(self):
		class EbuildTestCaseEbuildFile(object):
			""" Lazy ebuild contents evaluator for EbuildTestCase. """
			def __init__(self, parent):
				""" Instantiate the evaluator for test case <parent>. """
				assert(isinstance(parent, EbuildTestCase))
				self._parent = parent

			def __str__(self):
				""" Return the ebuild contents as string. """
				contents = [ebuild_header % (self._parent.eapi,
					' '.join(['pms-test'] + self._parent.inherits))]

				for k, v in self._parent.ebuild_vars.items():
					contents.append('%s="%s"\n' % (k, v)) # XXX: escaping

				for f, lines in self._parent.phase_funcs.items():
					if not lines:
						continue

					contents.append('\n%s() {\n' % f)
					for l in lines:
						contents.append('\t%s\n' % l) # XXX: smarter tabs
					contents.append('}\n')

				return ''.join(contents)

		if not self._finalized:
			self._finalize()

		fn = 'pms-test/%s/%s.ebuild' % (self.pn, self.p)

		return {fn: EbuildTestCaseEbuildFile(self)}

	def clean(self, pm):
		if self.atom(pm) in pm.installed:
			pm.unmerge(self.cpv)

	def start(self, pm):
		pm.merge(self.cpv)

	def check_result(self, pm):
		"""
		Check the correctness of the result of test execution. By default,
		checks whether the ebuild was actually merged.
		"""

		merged = self.atom(pm) in pm.installed
		return (merged != self.expect_failure)