summaryrefslogtreecommitdiff
path: root/lib/testtools/doc
diff options
context:
space:
mode:
authorJelmer Vernooij <jelmer@samba.org>2011-12-08 21:21:59 +0100
committerJelmer Vernooij <jelmer@samba.org>2011-12-08 22:12:00 +0100
commit624a78d9f8214d21346b7791d3e2f2a57cb26688 (patch)
tree01024ad10aba1dc0f01f5455103a0d5f16165ab6 /lib/testtools/doc
parent03e5f581aed89b3eea5769a244864a0f9938ac59 (diff)
downloadsamba-624a78d9f8214d21346b7791d3e2f2a57cb26688.tar.gz
samba-624a78d9f8214d21346b7791d3e2f2a57cb26688.tar.bz2
samba-624a78d9f8214d21346b7791d3e2f2a57cb26688.zip
testtools: Update to new upstream revision.
Diffstat (limited to 'lib/testtools/doc')
-rw-r--r--lib/testtools/doc/for-test-authors.rst137
-rw-r--r--lib/testtools/doc/hacking.rst2
2 files changed, 137 insertions, 2 deletions
diff --git a/lib/testtools/doc/for-test-authors.rst b/lib/testtools/doc/for-test-authors.rst
index 04c4be6b0d..febbb84151 100644
--- a/lib/testtools/doc/for-test-authors.rst
+++ b/lib/testtools/doc/for-test-authors.rst
@@ -445,6 +445,110 @@ be able to do, if you think about it::
self.assertThat('foo', MatchesRegex('fo+'))
+File- and path-related matchers
+-------------------------------
+
+testtools also has a number of matchers to help with asserting things about
+the state of the filesystem.
+
+PathExists
+~~~~~~~~~~
+
+Matches if a path exists::
+
+ self.assertThat('/', PathExists())
+
+
+DirExists
+~~~~~~~~~
+
+Matches if a path exists and it refers to a directory::
+
+ # This will pass on most Linux systems.
+ self.assertThat('/home/', DirExists())
+ # This will not
+ self.assertThat('/home/jml/some-file.txt', DirExists())
+
+
+FileExists
+~~~~~~~~~~
+
+Matches if a path exists and it refers to a file (as opposed to a directory)::
+
+ # This will pass on most Linux systems.
+ self.assertThat('/bin/true', FileExists())
+ # This will not.
+ self.assertThat('/home/', FileExists())
+
+
+DirContains
+~~~~~~~~~~~
+
+Matches if the given directory contains the specified files and directories.
+Say we have a directory ``foo`` that has the files ``a``, ``b`` and ``c``,
+then::
+
+ self.assertThat('foo', DirContains(['a', 'b', 'c']))
+
+will match, but::
+
+ self.assertThat('foo', DirContains(['a', 'b']))
+
+will not.
+
+The matcher sorts both the input and the list of names we get back from the
+filesystem.
+
+You can use this in a more advanced way, and match the sorted directory
+listing against an arbitrary matcher::
+
+ self.assertThat('foo', DirContains(matcher=Contains('a')))
+
+
+FileContains
+~~~~~~~~~~~~
+
+Matches if the given file has the specified contents. Say there's a file
+called ``greetings.txt`` with the contents, ``Hello World!``::
+
+ self.assertThat('greetings.txt', FileContains("Hello World!"))
+
+will match.
+
+You can also use this in a more advanced way, and match the contents of the
+file against an arbitrary matcher::
+
+ self.assertThat('greetings.txt', FileContains(matcher=Contains('!')))
+
+
+HasPermissions
+~~~~~~~~~~~~~~
+
+Used for asserting that a file or directory has certain permissions. Uses
+octal-mode permissions for both input and matching. For example::
+
+ self.assertThat('/tmp', HasPermissions('1777'))
+ self.assertThat('id_rsa', HasPermissions('0600'))
+
+This is probably more useful on UNIX systems than on Windows systems.
+
+
+SamePath
+~~~~~~~~
+
+Matches if two paths actually refer to the same thing. The paths don't have
+to exist, but if they do exist, ``SamePath`` will resolve any symlinks.::
+
+ self.assertThat('somefile', SamePath('childdir/../somefile'))
+
+
+TarballContains
+~~~~~~~~~~~~~~~
+
+Matches the contents of a tarball. In many ways, much like ``DirContains``,
+but instead of matching on ``os.listdir`` matches on ``TarFile.getnames``.
+
+
Combining matchers
------------------
@@ -550,7 +654,11 @@ more information in error messages is a big help.
The second reason is that it is sometimes useful to give a name to a set of
matchers. ``has_und_at_both_ends`` is a bit contrived, of course, but it is
-clear.
+clear. The ``FileExists`` and ``DirExists`` matchers included in testtools
+are perhaps better real examples.
+
+If you want only the first mismatch to be reported, pass ``first_only=True``
+as a keyword parameter to ``MatchesAll``.
MatchesAny
@@ -595,6 +703,9 @@ For example::
This is useful for writing custom, domain-specific matchers.
+If you want only the first mismatch to be reported, pass ``first_only=True``
+to ``MatchesListwise``.
+
MatchesSetwise
~~~~~~~~~~~~~~
@@ -645,6 +756,30 @@ object must equal each attribute of the example object. For example::
is exactly equivalent to ``matcher`` in the previous example.
+MatchesPredicate
+~~~~~~~~~~~~~~~~
+
+Sometimes, all you want to do is create a matcher that matches if a given
+function returns True, and mismatches if it returns False.
+
+For example, you might have an ``is_prime`` function and want to make a
+matcher based on it::
+
+ def test_prime_numbers(self):
+ IsPrime = MatchesPredicate(is_prime, '%s is not prime.')
+ self.assertThat(7, IsPrime)
+ self.assertThat(1983, IsPrime)
+ # This will fail.
+ self.assertThat(42, IsPrime)
+
+Which will produce the error message::
+
+ Traceback (most recent call last):
+ File "...", line ..., in test_prime_numbers
+ self.assertThat(42, IsPrime)
+ MismatchError: 42 is not prime.
+
+
Raises
~~~~~~
diff --git a/lib/testtools/doc/hacking.rst b/lib/testtools/doc/hacking.rst
index b9f5ff22c6..fa67887abd 100644
--- a/lib/testtools/doc/hacking.rst
+++ b/lib/testtools/doc/hacking.rst
@@ -147,7 +147,7 @@ Release tasks
.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
.. _unittest: http://docs.python.org/library/unittest.html
-.. _~testtools-dev: https://launchpad.net/~testtools-dev
+.. _~testtools-committers: https://launchpad.net/~testtools-committers
.. _MIT license: http://www.opensource.org/licenses/mit-license.php
.. _Sphinx: http://sphinx.pocoo.org/
.. _restructuredtext: http://docutils.sourceforge.net/rst.html