anon/cmdtest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
Johan Holmberg 2016-11-08 09:59:22 +01:00
parent fd4b3e09af
commit 4bfa4a625d
2 changed files with 84 additions and 14 deletions

49
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 &quot;environment&quot; 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 &quot;not on linux&quot;
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 &quot;stdout_equal&quot; for how &quot;content&quot; 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 &quot;stdout_equal&quot; for how &quot;content&quot; 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 &quot;/&quot; 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 &quot;skipped&quot;, and also show up in the JUnit format XML
files (the intention is that this should work like the &quot;assume-functions&quot;
in recent versions of JUnit).</dd>
<dt><tt class="docutils literal">touch_file(filename)</tt></dt>
<dd>&quot;touch&quot; a file inside the &quot;work directory&quot;.
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>

49
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