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

Document more methods, handling of current directory. Change Hudson --> Jenkins.

Browse Source
This commit is contained in:
Johan Holmberg
2014-02-16 18:33:31 +01:00
parent 0683c9eb32
commit d9f0a4e903
2 changed files with 95 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.9.1: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<title>Cmdtest User Guide</title>
<style type="text/css">
@ -411,7 +411,7 @@ call.</p>
skipped. But all errors occurring at the same command will be reported.</p>
<p>Cmdtest can also be directed to write an XML file on the same format as
that used by Ant/JUnit. This makes it possible to use Cmdtest together
with <a class="reference external" href="http://en.wikipedia.org/wiki/Continuous_integration">continuous integration</a> servers like <a class="reference external" href="https://hudson.dev.java.net">Hudson</a>.</p>
with <a class="reference external" href="http://en.wikipedia.org/wiki/Continuous_integration">continuous integration</a> servers like <a class="reference external" href="http://jenkins-ci.org">Jenkins</a>.</p>
<p>The exit status of <tt class="docutils literal">cmdtest</tt> will be non-zero if some errors occurred,
otherwise zero. If errors should not affect exit code, the
command line option <tt class="docutils literal"><span class="pre">--no-exit-code</span></tt> can be used.</p>
@ -487,10 +487,16 @@ Beside these methods the test can of course also contain arbitrary Ruby-code.</p
<h1><a class="toc-backref" href="#id6">Work directory</a></h1>
<p>All tests are performed in a &quot;clean&quot; temporary directory, here called the &quot;work directory&quot;.
When the <tt class="docutils literal">setup</tt>, <tt class="docutils literal">test_*</tt> and <tt class="docutils literal">teardown</tt> methods are called the current directory
will be the &quot;work directory&quot; (unless <tt class="docutils literal">Dir.chdir</tt> is called by the methods themselves).</p>
will be the &quot;work directory&quot; (unless <tt class="docutils literal">chdir</tt> is called by the methods themselves).</p>
<p>Several of the assertions and helper functions take filename arguments
that are evaluated relative to the &quot;work directory&quot; (or sometimes the
current directory if they differ).</p>
<p>To support running <tt class="docutils literal">cmdtest</tt> in parallel, methods such as
<tt class="docutils literal">File.open</tt> and <tt class="docutils literal">Dir.chdir</tt> should not be used in the test
methods. Instead methods supplied by Cmdtest, such as <tt class="docutils literal">create_file</tt>
and <tt class="docutils literal">chdir</tt> should be used. The reason for this is that the <tt class="docutils literal">cmdtest</tt> process
only has <strong>one</strong> current directory, so different threads can't set the
current directory without interfering with each other.</p>
</div>
<div class="section" id="specifying-files-directories">
<h1><a class="toc-backref" href="#id7">Specifying files / directories</a></h1>
@ -661,7 +667,7 @@ $ cmdtest --xml=reports/test-foo.xml
</pre>
<p>Write an XML-summary to the specified file. The file uses the same
format as <a class="reference external" href="http://en.wikipedia.org/wiki/JUnit">JUnit</a>, so it can be understood be continuous integration
servers such as <a class="reference external" href="https://hudson.dev.java.net">Hudson</a>.</p>
servers such as <a class="reference external" href="http://jenkins-ci.org">Jenkins</a>.</p>
</div>
</div>
<div class="section" id="reference-part">
@ -716,12 +722,14 @@ command. This assertion can be used when it doesn't matter which
of <tt class="docutils literal">created_files</tt>, <tt class="docutils literal">removed_files</tt> or <tt class="docutils literal">changed_files</tt> that apply
(cf. <tt class="docutils literal">written_files</tt>).</dd>
<dt><tt class="docutils literal"><span class="pre">changed_files(file1,...,fileN)</span></tt></dt>
<dd>Deprecated. Use <tt class="docutils literal">modified_files</tt> instead.</dd>
<dt><tt class="docutils literal"><span class="pre">created_files(file1,...,fileN)</span></tt></dt>
<dd>The specified files should have been created by the command.</dd>
<dt><tt class="docutils literal"><span class="pre">modified_files(file1,...,fileN)</span></tt></dt>
<dd>The specified files should have been modified by the command. A
file is considered modified if it existed before the command, and
something about the file has changed after the command (inode
number, modification date or content).</dd>
<dt><tt class="docutils literal"><span class="pre">created_files(file1,...,fileN)</span></tt></dt>
<dd>The specified files should have been created by the command.</dd>
<dt><tt class="docutils literal"><span class="pre">removed_files(file1,...,fileN)</span></tt></dt>
<dd>The specified files should have been removed by the command.</dd>
<dt><tt class="docutils literal"><span class="pre">written_files(file1,...,fileN)</span></tt></dt>
@ -771,6 +779,9 @@ interval given as argument.</dd>
<div class="section" id="helper-functions">
<h2><a class="toc-backref" href="#id19">Helper functions</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal">chdir(dir, &amp;block)</tt></dt>
<dd>Works like <tt class="docutils literal">Dir.chdir</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">create_file(filename, content)</tt></dt>
<dd>Create a file inside the &quot;work directory&quot;.
If the filename contains a directory part, intermediate directories are
@ -779,6 +790,24 @@ 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">dir_mkdir(file)</tt></dt>
<dd>Works like <tt class="docutils literal">Dir.mkdir</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">file_chmod(arg, file)</tt></dt>
<dd>Works like <tt class="docutils literal">File.chmod</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">file_open(file, *args, &amp;block)</tt></dt>
<dd>Works like <tt class="docutils literal">File.open</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">file_read(file)</tt></dt>
<dd>Works like <tt class="docutils literal">File.read</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">file_symlink(file1, file2)</tt></dt>
<dd>Works like <tt class="docutils literal">File.symlink</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">file_utime(arg1, arg2, file)</tt></dt>
<dd>Works like <tt class="docutils literal">File.utime</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</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>
@ -800,6 +829,12 @@ relative to the current directory in effect at the time of the call
are looked up using the modified <tt class="docutils literal">PATH</tt>. A typical use is to add the directory
where the executable tested is located. The argument <tt class="docutils literal">dir</tt> is evaluated
relative to the current directory in effect when <tt class="docutils literal">cmdtest</tt> was invoked.</dd>
<dt><tt class="docutils literal">remove_file(file)</tt></dt>
<dd>Works like <tt class="docutils literal">FileUtils.rm_f</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">remove_file_tree(file)</tt></dt>
<dd>Works like <tt class="docutils literal">FileUtils.rm_rf</tt>, but handles current directory correctly
under <tt class="docutils literal">cmdtest</tt>.</dd>
<dt><tt class="docutils literal">set_path(dir1, <span class="pre">...,</span> dirN)</tt></dt>
<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>
@ -815,7 +850,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: 2013-08-13.
Generated on: 2014-02-16.
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>

60
doc/cmdtest.txt

@ -100,7 +100,7 @@ skipped. But all errors occurring at the same command will be reported.
Cmdtest can also be directed to write an XML file on the same format as
that used by Ant/JUnit. This makes it possible to use Cmdtest together
with `continuous integration`_ servers like Hudson_.
with `continuous integration`_ servers like Jenkins_.
The exit status of ``cmdtest`` will be non-zero if some errors occurred,
otherwise zero. If errors should not affect exit code, the
@ -183,12 +183,19 @@ Work directory
All tests are performed in a "clean" temporary directory, here called the "work directory".
When the ``setup``, ``test_*`` and ``teardown`` methods are called the current directory
will be the "work directory" (unless ``Dir.chdir`` is called by the methods themselves).
will be the "work directory" (unless ``chdir`` is called by the methods themselves).
Several of the assertions and helper functions take filename arguments
that are evaluated relative to the "work directory" (or sometimes the
current directory if they differ).
To support running ``cmdtest`` in parallel, methods such as
``File.open`` and ``Dir.chdir`` should not be used in the test
methods. Instead methods supplied by Cmdtest, such as ``create_file``
and ``chdir`` should be used. The reason for this is that the ``cmdtest`` process
only has **one** current directory, so different threads can't set the
current directory without interfering with each other.
Specifying files / directories
------------------------------
@ -364,7 +371,7 @@ Run all tests found in test files in the "examples" directory
Write an XML-summary to the specified file. The file uses the same
format as JUnit_, so it can be understood be continuous integration
servers such as Hudson_.
servers such as Jenkins_.
Reference Part
--------------
@ -423,14 +430,17 @@ Assertions - files
(cf. ``written_files``).
``changed_files(file1,...,fileN)``
Deprecated. Use ``modified_files`` instead.
``created_files(file1,...,fileN)``
The specified files should have been created by the command.
``modified_files(file1,...,fileN)``
The specified files should have been modified by the command. A
file is considered modified if it existed before the command, and
something about the file has changed after the command (inode
number, modification date or content).
``created_files(file1,...,fileN)``
The specified files should have been created by the command.
``removed_files(file1,...,fileN)``
The specified files should have been removed by the command.
@ -485,6 +495,10 @@ Assertions - misc
Helper functions
++++++++++++++++
``chdir(dir, &block)``
Works like ``Dir.chdir``, but handles current directory correctly
under ``cmdtest``.
``create_file(filename, content)``
Create a file inside the "work directory".
If the filename contains a directory part, intermediate directories are
@ -494,6 +508,30 @@ Helper functions
The filename is evaluated relative to the current directory at the
time of the call.
``dir_mkdir(file)``
Works like ``Dir.mkdir``, but handles current directory correctly
under ``cmdtest``.
``file_chmod(arg, file)``
Works like ``File.chmod``, but handles current directory correctly
under ``cmdtest``.
``file_open(file, *args, &block)``
Works like ``File.open``, but handles current directory correctly
under ``cmdtest``.
``file_read(file)``
Works like ``File.read``, but handles current directory correctly
under ``cmdtest``.
``file_symlink(file1, file2)``
Works like ``File.symlink``, but handles current directory correctly
under ``cmdtest``.
``file_utime(arg1, arg2, file)``
Works like ``File.utime``, but handles current directory correctly
under ``cmdtest``.
``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.
@ -520,6 +558,14 @@ Helper functions
where the executable tested is located. The argument ``dir`` is evaluated
relative to the current directory in effect when ``cmdtest`` was invoked.
``remove_file(file)``
Works like ``FileUtils.rm_f``, but handles current directory correctly
under ``cmdtest``.
``remove_file_tree(file)``
Works like ``FileUtils.rm_rf``, but handles current directory correctly
under ``cmdtest``.
``set_path(dir1, ..., dirN)``
Set ``PATH`` to the given directories, so commands executed via ``cmd``
are looked up using the modified ``PATH``. This method sets the whole ``PATH``
@ -535,4 +581,4 @@ Helper functions
.. _`Test::Unit`: http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html
.. _`continuous integration`: http://en.wikipedia.org/wiki/Continuous_integration
.. _Hudson: https://hudson.dev.java.net
.. _Jenkins: http://jenkins-ci.org