[gentoo-commits] proj/pms-test-suite:master commit in: /, doc/

["Michał Górny" <mgorny@gentoo.org>]

commit:     27c9602f603f08ece5ed0b65fbad6624257eb368
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Wed Jun 22 07:44:23 2011 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Wed Jun 22 07:44:23 2011 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/pms-test-suite.git;a=commit;h=27c9602f

Add docs on EbuildTestCase use.

---
 doc/ebuild-test-case.md |   98 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/library-format.md   |    2 +-
 setup.py                |    3 +-
 3 files changed, 101 insertions(+), 2 deletions(-)

diff --git a/doc/ebuild-test-case.md b/doc/ebuild-test-case.md
new file mode 100644
index 0000000..c297a2a
--- /dev/null
+++ b/doc/ebuild-test-case.md
@@ -0,0 +1,98 @@
+EbuildTestCase
+==============
+
+Quick description
+-----------------
+
+`EbuildTestCase` is the most common test case implementation. It assumes
+that a particular test case consists of a single ebuild which is supposed
+to be run by PM.
+
+`EbuildTestCase` is declared in `PMSTestSuite.library.case` module.
+
+By default, `EbuildTestCase` checks the result result by checking whether it was
+merged.
+
+
+Using EbuildTestCase
+--------------------
+
+An example use case would be like:
+
+	from PMSTestSuite.library.case import EbuildTestCase
+
+	class RandomExampleTest(EbuildTestCase):
+		""" An absolutely random test. """
+
+		relevant_eapis = (0, 1, 2, 4)
+		expect_failure = True
+
+		ebuild_vars = {
+			'HOMEPAGE': 'http://example.com/'
+		}
+		phase_funcs = {
+			'src_compile': [
+				'echo 11',
+				'die 12'
+			]
+		}
+
+Where:
+
+- the class name is used to construct the test name (it would `random-example`
+  here),
+- the docstring is used to form the ebuild `DESCRIPTION` (it can be overrode
+  using `ebuild_vars['DESCRIPTION']`,
+- `relevant_eapis` (_iterable of strings_) specifies for which EAPIs the test
+  will be performed,
+- `expect_failure` (_bool_, default: _False_) specifies whether the ebuild is
+  supposed to fail merge,
+- `ebuild_vars` (_dict of str -> str_) specifies additional global ebuild
+  variables to declare in the ebuild,
+- `phase_funcs` (_dict of str -> iterable of strings_) specifies the contents of
+  ebuild phase functions. Each iterable element represents a single line.
+
+
+Extending EbuildTestCase
+------------------------
+
+If you'd like to create more complex test case, you'll probably need to override
+some methods of the `EbuildTestCase` class. It could look like:
+
+	from PMSTestSuite.library.case import EbuildTestCase
+
+	class MoreComplexExampleTest(EbuildTestCase):
+		""" Now overriding methods! """
+
+		relevant_eapis = (0, 1, 2)
+
+		phase_funcs = {
+			'src_compile': [
+				'echo 11',
+				'[[ ${EAPI} -eq 2 ]] && die 12'
+			]
+		}
+
+		def __init__(self, eapi):
+			EbuildTestCase.__init__(self, eapi)
+			self.phase_funcs['src_install'].append('echo nah(%d)!' % eapi)
+
+		def check_result(self, pm):
+			res = EbuildTestCase.check_result(self, pm)
+			return (res == (self.eapi != 2))
+
+Overriding `__init__()` allows you to perform additional test modifications when
+it is instantiated for a particular EAPI. But remember to call superclass'
+`__init__()` as well as it sets `self.eapi` and deepcopies all the standard
+variables (like `phase_funcs` and `ebuild_vars`). Without that, the phase func
+change would be applied to a shared, class-defined variable!
+
+Overriding `check_result()` allows you to check the test results your own way.
+You can call superclass' `check_result()` to check whether the ebuild was merged
+into vdb (or the opposite, if `expect_failure` is _True_).
+
+Thus, the above example just adds a random, EAPI-dependant output into
+`src_install()`, and expects the test to succeed if `eapi != 2` and fail
+otherwise.
+
+<!-- vim:se syn=markdown tw=80 :-->

diff --git a/doc/library-format.md b/doc/library-format.md
index 09ad8e3..265e631 100644
--- a/doc/library-format.md
+++ b/doc/library-format.md
@@ -89,4 +89,4 @@ More information
 3. `pydoc PMSTestSuite.pm.PackageManager`
 4. `pydoc PMSTestSuite.library.depend_case`
 
-<!-- vim:se syn=markdown :-->
+<!-- vim:se syn=markdown tw=80 :-->

diff --git a/setup.py b/setup.py
index a9beac7..a0e47ac 100755
--- a/setup.py
+++ b/setup.py
@@ -124,7 +124,8 @@ setup(
 			'pms-tester'
 		],
 		docs = [
-			'doc/library-format.md'
+			'doc/library-format.md',
+			'doc/ebuild-test-case.md'
 		],
 
 		classifiers = [