diff --git a/doc/cmdtest.html b/doc/cmdtest.html
index 2c486fa..760829d 100644
--- a/doc/cmdtest.html
+++ b/doc/cmdtest.html
@@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>Cmdtest User Guide</title>
<style type="text/css">
@@ -340,6 +340,7 @@ be made about the side effects performed by a command:</p>
<li>the content of standard error</li>
<li>newly created/removed/changed files, or other changes to the
filesystem</li>
+<li>encoding of a file (eg. UTF-8)</li>
</ul>
</div>
<div class="section" id="a-simple-example">
@@ -480,8 +481,8 @@ end
command should be described as an assertion in the do-block. The list
of possible assertions includes: <tt class="docutils literal">exit_zero</tt>, <tt class="docutils literal">exit_nonzero</tt>,
<tt class="docutils literal">exit_status</tt>, <tt class="docutils literal">created_files</tt>, <tt class="docutils literal">changed_files</tt>, <tt class="docutils literal">removed_files</tt>,
-<tt class="docutils literal">written_files</tt>, <tt class="docutils literal">affected_files</tt>, <tt class="docutils literal">file_equal</tt>, <tt class="docutils literal">stdout_equal</tt>
-and <tt class="docutils literal">stderr_equal</tt>.</p>
+<tt class="docutils literal">written_files</tt>, <tt class="docutils literal">affected_files</tt>, <tt class="docutils literal">file_equal</tt>, <tt class="docutils literal">file_encoding</tt>,
+<tt class="docutils literal">stdout_equal</tt> and <tt class="docutils literal">stderr_equal</tt>.</p>
<p>In addition to the assertions there are other helper-functions to set
up the "environment" for the commands and assertions. An example is
the creation of files:</p>
@@ -499,6 +500,16 @@ end
<p>The list of such helper functions includes:
<tt class="docutils literal">create_file</tt>, <tt class="docutils literal">touch_file</tt>, <tt class="docutils literal">import_file</tt> , <tt class="docutils literal">import_directory</tt> and <tt class="docutils literal">ignore_file</tt>.
Beside these methods the test can of course also contain arbitrary Ruby-code.</p>
+<p>Some test are not applicable under all circumstances. A test can for example be Linux specific.
+Then the function <tt class="docutils literal">skip_test</tt> can be used, like this:</p>
+<pre class="literal-block">
+def test_linux_stuff
+ if RUBY_PLATFORM !~ /linux/
+ skip_test "not on linux"
+ end
+ ... the actual tests ...
+end
+</pre>
</div>
<div class="section" id="work-directory">
<h1><a class="toc-backref" href="#id6">Work directory</a></h1>
@@ -622,8 +633,9 @@ $ cmdtest examples /stdin/ /stdout/
<p>The available options can be seen by using the <tt class="docutils literal"><span class="pre">-h</span></tt> option:</p>
<pre class="literal-block">
$ cmdtest -h
-usage: cmdtest [-h] [--version] [-q] [-v] [--fast] [-j N] [--test TEST]
- [--xml FILE] [--no-exit-code] [-i] [--slave SLAVE]
+usage: cmdtest [-h] [--shortversion] [--version] [-q] [-v] [--diff] [--no-diff]
+ [--fast] [-j N] [--test TEST] [--xml FILE] [--no-exit-code]
+ [--stop-on-error] [-i] [--slave SLAVE]
[arg [arg ...]]
positional arguments:
@@ -631,15 +643,18 @@ positional arguments:
optional arguments:
-h, --help show this help message and exit
- -h, --help show this help message and exit
+ --shortversion show just version number
--version show version
- -q, --quiet be more quiet by skipping some non-essential output
+ -q, --quiet be more quiet
-v, --verbose be more verbose
+ --diff diff output (default)
+ --no-diff old non-diff output
--fast run fast without waiting for unique mtime:s
-j N, --parallel N build in parallel
--test TEST only run named test
--xml FILE write summary on JUnit format
--no-exit-code exit with 0 status even after errors
+ --stop-on-error exit after first error
-i, --incremental incremental mode
--slave SLAVE run in slave mode
</pre>
@@ -755,6 +770,10 @@ case special (when the file is created).</dd>
See "stdout_equal" for how "content" can be specified.</dd>
<dt><tt class="docutils literal">file_not_equal(file, content)</tt></dt>
<dd>Like <tt class="docutils literal">file_equal</tt> but with inverted test.</dd>
+<dt><tt class="docutils literal">file_encoding(file, enc, bom: nil)</tt></dt>
+<dd>Assert that the file uses encoding <tt class="docutils literal">enc</tt>. This is verified by reading
+the file using that encoding. The optional <tt class="docutils literal">bom</tt> argument can be used
+to assert the existence/non-existence of a Unicode BOM.</dd>
<dt><tt class="docutils literal">stderr_equal(content)</tt></dt>
<dd>Assert that the standard error of the command matches the given content.
See "stdout_equal" for how "content" can be specified.</dd>
@@ -796,6 +815,12 @@ The content can be specified either as an array of lines or as
a string with the content of the whole file.
The filename is evaluated relative to the current directory at the
time of the call.</dd>
+<dt><tt class="docutils literal">dont_ignore_files(file1, <span class="pre">...,</span> fileN)</tt></dt>
+<dd>Don't ignore the specified files when looking for differences in the filesystem.
+This overrides a previous call to <tt class="docutils literal">ignore_files</tt>.
+If a previous call to <tt class="docutils literal">ignore_files</tt> ignored a whole directory tree, the call to
+<tt class="docutils literal">dont_ignore_files</tt> can reverse the effect for specific files inside that
+directory tree.</dd>
<dt><tt class="docutils literal">ignore_file(file)</tt></dt>
<dd>Ignore the specified file when looking for differences in the filesystem.
A subdirectory can be ignored by giving a trailing "/" to the name.</dd>
@@ -833,6 +858,14 @@ by later calls to <tt class="docutils literal">cmd</tt>.</dd>
<dd>Set <tt class="docutils literal">PATH</tt> to the given directories, so commands executed via <tt class="docutils literal">cmd</tt>
are looked up using the modified <tt class="docutils literal">PATH</tt>. This method sets the whole <tt class="docutils literal">PATH</tt>
rather than modifying it (in contrast to <tt class="docutils literal">prepend_path</tt> and <tt class="docutils literal">prepend_local_path</tt>).</dd>
+<dt><tt class="docutils literal">skip_test(reason)</tt></dt>
+<dd>If a test method should not be run for some reason (eg. wrong platform),
+this can be signaled to <tt class="docutils literal">cmdtest</tt> by calling
+<tt class="docutils literal">skip_test</tt> at the beginning of the test method. The argument
+should mention why the test is skipped. Such tests will be
+reported as "skipped", and also show up in the JUnit format XML
+files (the intention is that this should work like the "assume-functions"
+in recent versions of JUnit).</dd>
<dt><tt class="docutils literal">touch_file(filename)</tt></dt>
<dd>"touch" a file inside the "work directory".
The filename is evaluated relative to the current directory at the
@@ -865,7 +898,7 @@ time of the call.</dd>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="cmdtest.txt">View document source</a>.
-Generated on: 2016-04-14.
+Generated on: 2016-11-08.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
diff --git a/doc/cmdtest.txt b/doc/cmdtest.txt
index e40114d..e2d6ae1 100644
--- a/doc/cmdtest.txt
+++ b/doc/cmdtest.txt
@@ -25,6 +25,8 @@ be made about the side effects performed by a command:
- newly created/removed/changed files, or other changes to the
filesystem
+- encoding of a file (eg. UTF-8)
+
A simple example
----------------
@@ -172,8 +174,8 @@ The idea is that all differences in behaviour from the trivial ``true``
command should be described as an assertion in the do-block. The list
of possible assertions includes: ``exit_zero``, ``exit_nonzero``,
``exit_status``, ``created_files``, ``changed_files``, ``removed_files``,
-``written_files``, ``affected_files``, ``file_equal``, ``stdout_equal``
-and ``stderr_equal``.
+``written_files``, ``affected_files``, ``file_equal``, ``file_encoding``,
+``stdout_equal`` and ``stderr_equal``.
In addition to the assertions there are other helper-functions to set
up the "environment" for the commands and assertions. An example is
@@ -193,6 +195,15 @@ The list of such helper functions includes:
``create_file``, ``touch_file``, ``import_file`` , ``import_directory`` and ``ignore_file``.
Beside these methods the test can of course also contain arbitrary Ruby-code.
+Some test are not applicable under all circumstances. A test can for example be Linux specific.
+Then the function ``skip_test`` can be used, like this::
+
+ def test_linux_stuff
+ if RUBY_PLATFORM !~ /linux/
+ skip_test "not on linux"
+ end
+ ... the actual tests ...
+ end
Work directory
--------------
@@ -331,8 +342,9 @@ Options
The available options can be seen by using the ``-h`` option::
$ cmdtest -h
- usage: cmdtest [-h] [--version] [-q] [-v] [--fast] [-j N] [--test TEST]
- [--xml FILE] [--no-exit-code] [-i] [--slave SLAVE]
+ usage: cmdtest [-h] [--shortversion] [--version] [-q] [-v] [--diff] [--no-diff]
+ [--fast] [-j N] [--test TEST] [--xml FILE] [--no-exit-code]
+ [--stop-on-error] [-i] [--slave SLAVE]
[arg [arg ...]]
positional arguments:
@@ -340,18 +352,22 @@ The available options can be seen by using the ``-h`` option::
optional arguments:
-h, --help show this help message and exit
- -h, --help show this help message and exit
+ --shortversion show just version number
--version show version
- -q, --quiet be more quiet by skipping some non-essential output
+ -q, --quiet be more quiet
-v, --verbose be more verbose
+ --diff diff output (default)
+ --no-diff old non-diff output
--fast run fast without waiting for unique mtime:s
-j N, --parallel N build in parallel
--test TEST only run named test
--xml FILE write summary on JUnit format
--no-exit-code exit with 0 status even after errors
+ --stop-on-error exit after first error
-i, --incremental incremental mode
--slave SLAVE run in slave mode
+
Commandline Examples
++++++++++++++++++++
@@ -476,6 +492,11 @@ These methods should only be used inside a ``cmd`` block.
``file_not_equal(file, content)``
Like ``file_equal`` but with inverted test.
+``file_encoding(file, enc, bom: nil)``
+ Assert that the file uses encoding ``enc``. This is verified by reading
+ the file using that encoding. The optional ``bom`` argument can be used
+ to assert the existence/non-existence of a Unicode BOM.
+
``stderr_equal(content)``
Assert that the standard error of the command matches the given content.
See "stdout_equal" for how "content" can be specified.
@@ -523,6 +544,13 @@ or in the ``setup`` method.
The filename is evaluated relative to the current directory at the
time of the call.
+``dont_ignore_files(file1, ..., fileN)``
+ Don't ignore the specified files when looking for differences in the filesystem.
+ This overrides a previous call to ``ignore_files``.
+ If a previous call to ``ignore_files`` ignored a whole directory tree, the call to
+ ``dont_ignore_files`` can reverse the effect for specific files inside that
+ directory tree.
+
``ignore_file(file)``
Ignore the specified file when looking for differences in the filesystem.
A subdirectory can be ignored by giving a trailing "/" to the name.
@@ -569,6 +597,15 @@ or in the ``setup`` method.
are looked up using the modified ``PATH``. This method sets the whole ``PATH``
rather than modifying it (in contrast to ``prepend_path`` and ``prepend_local_path``).
+``skip_test(reason)``
+ If a test method should not be run for some reason (eg. wrong platform),
+ this can be signaled to ``cmdtest`` by calling
+ ``skip_test`` at the beginning of the test method. The argument
+ should mention why the test is skipped. Such tests will be
+ reported as "skipped", and also show up in the JUnit format XML
+ files (the intention is that this should work like the "assume-functions"
+ in recent versions of JUnit).
+
``touch_file(filename)``
"touch" a file inside the "work directory".
The filename is evaluated relative to the current directory at the