[robotframework commit] r375 - in trunk/doc/userguide: . src/CreatingTestData

0 views

Skip to first unread message

codesite...@google.com

unread,

Jul 22, 2008, 7:07:49 AM7/22/08

to robotframe...@googlegroups.com

Author: laukpe
Date: Tue Jul 22 04:07:21 2008
New Revision: 375

Modified:
trunk/doc/userguide/RobotFrameworkUserGuide.html
trunk/doc/userguide/src/CreatingTestData/UsingTestLibraries.txt

Log:
added information about importing test libs using physical path (issue 41)

Modified: trunk/doc/userguide/RobotFrameworkUserGuide.html
==============================================================================
--- trunk/doc/userguide/RobotFrameworkUserGuide.html (original)
+++ trunk/doc/userguide/RobotFrameworkUserGuide.html Tue Jul 22
04:07:21 2008
@@ -450,7 +450,7 @@
<body>
<div class="document" id="robot-framework-user-guide">
<h1 class="title">Robot Framework User Guide</h1>
-<h2 class="subtitle" id="version-version">Version trunk 20080624</h2>
+<h2 class="subtitle" id="version-version">Version trunk 20080722</h2>

<div class="section" id="getting-started">
-<h1><a class="toc-backref" href="#id118">1   Getting started</a></h1>
+<h1><a class="toc-backref" href="#id119">1   Getting started</a></h1>
<div class="contents local topic" id="contents">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#introduction" id="id146">1.1   Introduction</a></li>
-<li><a class="reference internal" href="#copyright-and-license"
id="id147">1.2   Copyright and license</a></li>
-<li><a class="reference internal"
href="#installation-and-uninstallation"
id="id148">1.3   Installation and uninstallation</a></li>
-<li><a class="reference internal" href="#demonstration" id="id149">1.4   Demonstration</a></li>
+<li><a class="reference internal" href="#introduction" id="id147">1.1   Introduction</a></li>
+<li><a class="reference internal" href="#copyright-and-license"
id="id148">1.2   Copyright and license</a></li>
+<li><a class="reference internal"
href="#installation-and-uninstallation"
id="id149">1.3   Installation and uninstallation</a></li>
+<li><a class="reference internal" href="#demonstration" id="id150">1.4   Demonstration</a></li>
</ul>
</div>
<div class="section" id="introduction">
-<h2><a class="toc-backref" href="#id146">1.1   Introduction</a></h2>
+<h2><a class="toc-backref" href="#id147">1.1   Introduction</a></h2>
<p>Robot Framework is a Python-based, extensible keyword-driven test
automation framework for end-to-end acceptance testing and
acceptance-test-driven development (ATDD). It can be used for testing
@@ -534,13 +534,13 @@
touching several technologies and interfaces.</p>
<div class="contents local topic" id="id1">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#why-robot-framework"
id="id150">1.1.1   Why Robot Framework?</a></li>
-<li><a class="reference internal" href="#screenshots" id="id151">1.1.2   Screenshots</a></li>
-<li><a class="reference internal" href="#high-level-architecture"
id="id152">1.1.3   High-level architecture</a></li>
+<li><a class="reference internal" href="#why-robot-framework"
id="id151">1.1.1   Why Robot Framework?</a></li>
+<li><a class="reference internal" href="#screenshots" id="id152">1.1.2   Screenshots</a></li>
+<li><a class="reference internal" href="#high-level-architecture"
id="id153">1.1.3   High-level architecture</a></li>
</ul>
</div>
<div class="section" id="why-robot-framework">
-<h3><a class="toc-backref" href="#id150">1.1.1   Why
Robot Framework?</a></h3>
+<h3><a class="toc-backref" href="#id151">1.1.1   Why
Robot Framework?</a></h3>
<ul class="simple">
<li>Enables easy-to-use tabular syntax for <a class="reference
internal" href="#creating-test-cases">creating test cases</a> in a uniform
way.</li>
@@ -567,7 +567,7 @@
</ul>
</div>
<div class="section" id="screenshots">
-<h3><a class="toc-backref" href="#id151">1.1.2   Screenshots</a></h3>
+<h3><a class="toc-backref" href="#id152">1.1.2   Screenshots</a></h3>
<p>Following image shows screenshots of Robot Framework <a
class="reference internal" href="#creating-test-data">test data</a>, <a
class="reference internal" href="#report-file">test
reports</a> and <a class="reference internal" href="#log-file">test logs</a>.</p>
<div class="figure">
@@ -580,7 +580,7 @@
</div>
</div>
<div class="section" id="high-level-architecture">
-<h3><a class="toc-backref"
href="#id152">1.1.3   High-level architecture</a></h3>
+<h3><a class="toc-backref"
href="#id153">1.1.3   High-level architecture</a></h3>
<p>Robot Framework handles the processing of test data, the
controlling of test
execution and the reporting of results for testing. The testing and interaction
with the target under test is done by test libraries that are plugged
into Robot
@@ -598,7 +598,7 @@
</div>
</div>
<div class="section" id="copyright-and-license">
-<h2><a class="toc-backref"
href="#id147">1.2   Copyright and license</a></h2>
+<h2><a class="toc-backref"
href="#id148">1.2   Copyright and license</a></h2>
<p>Robot Framework itself, test libraries and supporting tools
distributed with it,
as well as this user guide and other provided documentation have the following
copyright statement.</p>
@@ -620,30 +620,30 @@
</pre>
</div>
<div class="section" id="installation-and-uninstallation">
-<h2><a class="toc-backref"
href="#id148">1.3   Installation and uninstallation</a></h2>
+<h2><a class="toc-backref"
href="#id149">1.3   Installation and uninstallation</a></h2>
<div class="contents local topic" id="id8">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#id9" id="id153">1.3.1   Introduction</a></li>
-<li><a class="reference internal" href="#preconditions" id="id154">1.3.2   Preconditions</a><ul>
-<li><a class="reference internal" href="#python-installation"
id="id155">Python installation</a></li>
-<li><a class="reference internal" href="#jython-installation"
id="id156">Jython installation</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#installation" id="id157">1.3.3   Installation</a><ul>
-<li><a class="reference internal" href="#installing-from-source"
id="id158">Installing from source</a></li>
-<li><a class="reference internal" href="#using-binary-installers"
id="id159">Using binary installers</a></li>
-<li><a class="reference internal" href="#manual-installation"
id="id160">Manual installation</a></li>
-<li><a class="reference internal" href="#where-files-are-installed"
id="id161">Where files are installed</a></li>
-<li><a class="reference internal" href="#setting-up-environment"
id="id162">Setting up environment</a></li>
-<li><a class="reference internal" href="#verifying-installation"
id="id163">Verifying installation</a></li>
+<li><a class="reference internal" href="#id9" id="id154">1.3.1   Introduction</a></li>
+<li><a class="reference internal" href="#preconditions" id="id155">1.3.2   Preconditions</a><ul>
+<li><a class="reference internal" href="#python-installation"
id="id156">Python installation</a></li>
+<li><a class="reference internal" href="#jython-installation"
id="id157">Jython installation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#installation" id="id158">1.3.3   Installation</a><ul>
+<li><a class="reference internal" href="#installing-from-source"
id="id159">Installing from source</a></li>
+<li><a class="reference internal" href="#using-binary-installers"
id="id160">Using binary installers</a></li>
+<li><a class="reference internal" href="#manual-installation"
id="id161">Manual installation</a></li>
+<li><a class="reference internal" href="#where-files-are-installed"
id="id162">Where files are installed</a></li>
+<li><a class="reference internal" href="#setting-up-environment"
id="id163">Setting up environment</a></li>
+<li><a class="reference internal" href="#verifying-installation"
id="id164">Verifying installation</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#uninstallation" id="id164">1.3.4   Uninstallation</a></li>
-<li><a class="reference internal" href="#upgrading" id="id165">1.3.5   Upgrading</a></li>
+<li><a class="reference internal" href="#uninstallation" id="id165">1.3.4   Uninstallation</a></li>
+<li><a class="reference internal" href="#upgrading" id="id166">1.3.5   Upgrading</a></li>
</ul>
</div>
<div class="section" id="id9">
-<h3><a class="toc-backref" href="#id153">1.3.1   Introduction</a></h3>
+<h3><a class="toc-backref" href="#id154">1.3.1   Introduction</a></h3>
<p>There are two ways to install Robot Framework:</p>
<dl class="docutils">
<dt><a class="reference internal"
href="#installing-from-source">Installing from source</a></dt>
@@ -664,12 +664,12 @@
<a class="reference external" href="http://source.robotframework.org">http://source.robotframework.org</a>.</p>
</div>
<div class="section" id="preconditions">
-<h3><a class="toc-backref" href="#id154">1.3.2   Preconditions</a></h3>
+<h3><a class="toc-backref" href="#id155">1.3.2   Preconditions</a></h3>
<p>Robot Framework runs both on <a class="reference external"
href="http://www.python.org/">Python</a> and <a class="reference
external" href="http://www.jython.org/">Jython</a>, and you need to have
at least one of them to be able to use it. However, the provided installers
only work with Python, so installing it is always recommended.</p>
<div class="section" id="python-installation">
-<h4><a class="toc-backref" href="#id155">Python installation</a></h4>
+<h4><a class="toc-backref" href="#id156">Python installation</a></h4>
<p>Python 2.5 is recommended, although Python 2.4 and 2.3 are also
supported. On most UNIX-like systems, you have Python installed by
default. If you are on Windows or otherwise need to install Python
@@ -687,7 +687,7 @@
</div>
</div>
<div class="section" id="jython-installation">
-<h4><a class="toc-backref" href="#id156">Jython installation</a></h4>
+<h4><a class="toc-backref" href="#id157">Jython installation</a></h4>
<p>Using test libraries implemented with Java or using Java tools
directly requires running Robot Framework on Jython, which then requires
Java Runtime Environment (JRE). The minimum required Java version is
@@ -739,9 +739,9 @@
</div>
</div>
<div class="section" id="installation">
-<h3><a class="toc-backref" href="#id157">1.3.3   Installation</a></h3>
+<h3><a class="toc-backref" href="#id158">1.3.3   Installation</a></h3>
<div class="section" id="installing-from-source">
-<h4><a class="toc-backref" href="#id158">Installing from source</a></h4>
+<h4><a class="toc-backref" href="#id159">Installing from source</a></h4>
<p>You can get Robot Framework source code either directly from version
control or as a source distribution package that needs to be extracted
somewhere. In both cases, you should have a directory containing the
@@ -782,13 +782,13 @@
</div>
</div>
<div class="section" id="using-binary-installers">
-<h4><a class="toc-backref" href="#id159">Using binary installers</a></h4>
+<h4><a class="toc-backref" href="#id160">Using binary installers</a></h4>
<p>Use the platform-specific way of installation. For example, on
Windows, double click the provided executable and follow
the instructions of the graphical installer.</p>
</div>
<div class="section" id="manual-installation">
-<h4><a class="toc-backref" href="#id160">Manual installation</a></h4>
+<h4><a class="toc-backref" href="#id161">Manual installation</a></h4>
<p>If you do not want to install Python, or for some other reason do not
want to use any automatic way of installing Robot Framework, you can
always do it manually following these steps:</p>
@@ -803,7 +803,7 @@
</ol>
</div>
<div class="section" id="where-files-are-installed">
-<h4><a class="toc-backref" href="#id161">Where files are installed</a></h4>
+<h4><a class="toc-backref" href="#id162">Where files are installed</a></h4>
<p>When an automatic installer is used, the Robot Framework code is copied
into a directory containing external Python modules. The actual
location is platform-specific, but on computers with a UNIX-like
@@ -820,7 +820,7 @@
<span class="path">[PythonInstallationDir]\Scripts</span>.</p>
</div>
<div class="section" id="setting-up-environment">
-<h4><a class="toc-backref" href="#id162">Setting up environment</a></h4>
+<h4><a class="toc-backref" href="#id163">Setting up environment</a></h4>
<p>After the installation, you might want to make Robot Framework's
runner scripts easily available from the command line. On UNIX-like
systems, that should be the case automatically, but for example on
@@ -843,7 +843,7 @@
</ol>
</div>
<div class="section" id="verifying-installation">
-<h4><a class="toc-backref" href="#id163">Verifying installation</a></h4>
+<h4><a class="toc-backref" href="#id164">Verifying installation</a></h4>
<p>To verify that the installation and environment setup were successful,
type:</p>
<pre class="literal-block">
@@ -861,7 +861,7 @@
</div>
</div>
<div class="section" id="uninstallation">
-<h3><a class="toc-backref" href="#id164">1.3.4   Uninstallation</a></h3>
+<h3><a class="toc-backref" href="#id165">1.3.4   Uninstallation</a></h3>
<p>If Robot Framework has been installed using a source distribution, it
can be uninstalled with command:</p>
<pre class="literal-block">
@@ -875,7 +875,7 @@
removing the <a class="reference internal"
href="#where-files-are-installed">framework code and runner scripts</a> manually.</p>
</div>
<div class="section" id="upgrading">
-<h3><a class="toc-backref" href="#id165">1.3.5   Upgrading</a></h3>
+<h3><a class="toc-backref" href="#id166">1.3.5   Upgrading</a></h3>
<p>The procedure when upgrading or downgrading Robot Framework depends on
the versions used:</p>
<ul class="simple">
@@ -895,7 +895,7 @@
</div>
</div>
<div class="section" id="demonstration">
-<h2><a class="toc-backref" href="#id149">1.4   Demonstration</a></h2>
+<h2><a class="toc-backref" href="#id150">1.4   Demonstration</a></h2>
<p>Robot Framework does not currently have a standalone demo, but we plan
to add one soon. However, SeleniumLibrary has an easily executable
demonstration test suite available. It contains a simple standalone
@@ -908,44 +908,44 @@
</div>
</div>
<div class="section" id="creating-test-data">
-<h1><a class="toc-backref" href="#id123">2   Creating
test data</a></h1>
+<h1><a class="toc-backref" href="#id124">2   Creating
test data</a></h1>
<div class="contents local topic" id="id11">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#test-data-syntax"
id="id166">2.1   Test data syntax</a></li>
-<li><a class="reference internal" href="#creating-test-cases"
id="id167">2.2   Creating test cases</a></li>
-<li><a class="reference internal" href="#creating-test-suites"
id="id168">2.3   Creating test suites</a></li>
-<li><a class="reference internal" href="#using-test-libraries"
id="id169">2.4   Using test libraries</a></li>
-<li><a class="reference internal" href="#variables" id="id170">2.5   Variables</a></li>
-<li><a class="reference internal" href="#creating-user-keywords"
id="id171">2.6   Creating user keywords</a></li>
-<li><a class="reference internal" href="#resource-and-variable-files"
id="id172">2.7   Resource and variable files</a></li>
-<li><a class="reference internal" href="#advanced-features"
id="id173">2.8   Advanced features</a></li>
+<li><a class="reference internal" href="#test-data-syntax"
id="id167">2.1   Test data syntax</a></li>
+<li><a class="reference internal" href="#creating-test-cases"
id="id168">2.2   Creating test cases</a></li>
+<li><a class="reference internal" href="#creating-test-suites"
id="id169">2.3   Creating test suites</a></li>
+<li><a class="reference internal" href="#using-test-libraries"
id="id170">2.4   Using test libraries</a></li>
+<li><a class="reference internal" href="#variables" id="id171">2.5   Variables</a></li>
+<li><a class="reference internal" href="#creating-user-keywords"
id="id172">2.6   Creating user keywords</a></li>
+<li><a class="reference internal" href="#resource-and-variable-files"
id="id173">2.7   Resource and variable files</a></li>
+<li><a class="reference internal" href="#advanced-features"
id="id174">2.8   Advanced features</a></li>
</ul>
</div>
<div class="section" id="test-data-syntax">
-<h2><a class="toc-backref" href="#id166">2.1   Test
data syntax</a></h2>
+<h2><a class="toc-backref" href="#id167">2.1   Test
data syntax</a></h2>
<p>This section covers Robot Framework's overall test data
syntax. The following sections will explain how to actually create test
cases, test suites and so on.</p>
<div class="contents local topic" id="id12">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#files-and-directories"
id="id174">2.1.1   Files and directories</a></li>
-<li><a class="reference internal" href="#supported-file-formats"
id="id175">2.1.2   Supported file formats</a><ul>
-<li><a class="reference internal" href="#html-format" id="id176">HTML format</a></li>
-<li><a class="reference internal" href="#tsv-format" id="id177">TSV format</a></li>
+<li><a class="reference internal" href="#files-and-directories"
id="id175">2.1.1   Files and directories</a></li>
+<li><a class="reference internal" href="#supported-file-formats"
id="id176">2.1.2   Supported file formats</a><ul>
+<li><a class="reference internal" href="#html-format" id="id177">HTML format</a></li>
+<li><a class="reference internal" href="#tsv-format" id="id178">TSV format</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#test-data-tables"
id="id178">2.1.3   Test data tables</a></li>
-<li><a class="reference internal" href="#rules-for-parsing-the-data"
id="id179">2.1.4   Rules for parsing the data</a><ul>
-<li><a class="reference internal" href="#ignored-data"
id="id180">Ignored data</a></li>
-<li><a class="reference internal" href="#escaping" id="id181">Escaping</a></li>
-<li><a class="reference internal" href="#handling-whitespace"
id="id182">Handling whitespace</a></li>
-<li><a class="reference internal"
href="#dividing-test-data-to-several-rows" id="id183">Dividing test
data to several rows</a></li>
+<li><a class="reference internal" href="#test-data-tables"
id="id179">2.1.3   Test data tables</a></li>
+<li><a class="reference internal" href="#rules-for-parsing-the-data"
id="id180">2.1.4   Rules for parsing the data</a><ul>
+<li><a class="reference internal" href="#ignored-data"
id="id181">Ignored data</a></li>
+<li><a class="reference internal" href="#escaping" id="id182">Escaping</a></li>
+<li><a class="reference internal" href="#handling-whitespace"
id="id183">Handling whitespace</a></li>
+<li><a class="reference internal"
href="#dividing-test-data-to-several-rows" id="id184">Dividing test
data to several rows</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="files-and-directories">
-<h3><a class="toc-backref" href="#id174">2.1.1   Files
and directories</a></h3>
+<h3><a class="toc-backref" href="#id175">2.1.1   Files
and directories</a></h3>
<p>The hierarchical structure for arranging test cases is built as follows:</p>
<ul class="simple">
<li>Test cases are created in <a class="reference internal"
href="#test-case-files">test case files</a>.</li>
@@ -967,7 +967,7 @@
</ul>
</div>
<div class="section" id="supported-file-formats">
-<h3><a class="toc-backref"
href="#id175">2.1.2   Supported file formats</a></h3>
+<h3><a class="toc-backref"
href="#id176">2.1.2   Supported file formats</a></h3>
<p>Robot Framework test data is defined in tabular format, using either
the HTML (hypertext markup language) or TSV (tab-separated values)
format. Robot Framework selects a parser for the test data based on
@@ -977,7 +977,7 @@
<p>Source distribution contains both HTML and TSV test data templates and
they can also be obtained from Robot Framework's <a class="reference
external" href="http://downloads.robotframework.org">download page</a>.</p>
<div class="section" id="html-format">
-<h4><a class="toc-backref" href="#id176">HTML format</a></h4>
+<h4><a class="toc-backref" href="#id177">HTML format</a></h4>
<p>In HTML files, the test data is defined in separate tables (see the
example below). Robot Framework recognizes these <a class="reference
internal" href="#test-data-tables">test data tables</a>
based on the text in their first cell. Everything outside recognized
@@ -1129,7 +1129,7 @@
</div>
</div>
<div class="section" id="tsv-format">
-<h4><a class="toc-backref" href="#id177">TSV format</a></h4>
+<h4><a class="toc-backref" href="#id178">TSV format</a></h4>
<p>In a TSV file, all the data is in one large table. <a
class="reference internal" href="#test-data-tables">Test data tables</a>
are recognized from an asterisk (*), followed by a normal table
name. Robot Framework ignores any other asterisks in the name, so it
@@ -1259,7 +1259,7 @@
</div>
</div>
<div class="section" id="test-data-tables">
-<h3><a class="toc-backref" href="#id178">2.1.3   Test
data tables</a></h3>
+<h3><a class="toc-backref" href="#id179">2.1.3   Test
data tables</a></h3>
<p>Test data is structured in four types of tables listed below. These
test data tables are identified by the first cell of the table, and
the last column in the table below lists different aliases that can be
@@ -1316,9 +1316,9 @@
</table>
</div>
<div class="section" id="rules-for-parsing-the-data">
-<h3><a class="toc-backref" href="#id179">2.1.4   Rules
for parsing the data</a></h3>
+<h3><a class="toc-backref" href="#id180">2.1.4   Rules
for parsing the data</a></h3>
<div class="section" id="ignored-data">
-<h4><a class="toc-backref" href="#id180">Ignored data</a></h4>
+<h4><a class="toc-backref" href="#id181">Ignored data</a></h4>
<p>When Robot Framework parses the test data, it ignores:</p>
<ul class="simple">
<li>All tables that do not start with a recognized table name in the
first cell</li>
@@ -1343,7 +1343,7 @@
from the <a class="reference internal" href="#builtin-library">BuiltIn library</a>.</p>
</div>
<div class="section" id="escaping">
-<h4><a class="toc-backref" href="#id181">Escaping</a></h4>
+<h4><a class="toc-backref" href="#id182">Escaping</a></h4>
<p>The escape character for the Robot Framework parser is the
backslash (\).
The escape character can be used as follows:</p>
<ul class="simple">
@@ -1361,7 +1361,7 @@
</ul>
</div>
<div class="section" id="handling-whitespace">
-<h4><a class="toc-backref" href="#id182">Handling whitespace</a></h4>
+<h4><a class="toc-backref" href="#id183">Handling whitespace</a></h4>
<p>Robot Framework handles whitespace, such as spaces, newlines and tabs,
the same way as they are handled in HTML. This means that Robot Framework:</p>
<ul class="simple">
@@ -1380,7 +1380,7 @@
</ul>
</div>
<div class="section" id="dividing-test-data-to-several-rows">
-<h4><a class="toc-backref" href="#id183">Dividing test data to several rows</a></h4>
+<h4><a class="toc-backref" href="#id184">Dividing test data to several rows</a></h4>
<p>If a keyword requires more arguments than there are columns available,
it is not necessary to add more columns. Instead, it is possible to
simply have three dots (<span class="code">...</span>) below the
original keyword name
@@ -1663,28 +1663,28 @@
</div>
</div>
<div class="section" id="creating-test-cases">
-<h2><a class="toc-backref" href="#id167">2.2   Creating
test cases</a></h2>
+<h2><a class="toc-backref" href="#id168">2.2   Creating
test cases</a></h2>
<p>This section describes the overall test case syntax. Organizing test
cases into <a class="reference internal"
href="#creating-test-suites">test suites</a> using <a class="reference
internal" href="#test-case-files">test case files</a> and <a
class="reference internal" href="#test-suite-directories">test suite
directories</a> is discussed in the next section.</p>
<div class="contents local topic" id="id14">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#test-case-syntax"
id="id184">2.2.1   Test case syntax</a><ul>
-<li><a class="reference internal" href="#basic-syntax"
id="id185">Basic syntax</a></li>
-<li><a class="reference internal"
href="#workflow-tests-vs-data-driven-tests" id="id186">Workflow tests
vs. data-driven tests</a></li>
-<li><a class="reference internal"
href="#settings-in-the-test-case-table" id="id187">Settings in the Test
Case table</a></li>
-<li><a class="reference internal"
href="#test-case-related-settings-in-the-setting-table"
id="id188">Test-case-related settings in the Setting table</a></li>
+<li><a class="reference internal" href="#test-case-syntax"
id="id185">2.2.1   Test case syntax</a><ul>
+<li><a class="reference internal" href="#basic-syntax"
id="id186">Basic syntax</a></li>
+<li><a class="reference internal"
href="#workflow-tests-vs-data-driven-tests" id="id187">Workflow tests
vs. data-driven tests</a></li>
+<li><a class="reference internal"
href="#settings-in-the-test-case-table" id="id188">Settings in the Test
Case table</a></li>
+<li><a class="reference internal"
href="#test-case-related-settings-in-the-setting-table"
id="id189">Test-case-related settings in the Setting table</a></li>
</ul>
</li>
-<li><a class="reference internal"
href="#test-case-name-and-documentation"
id="id189">2.2.2   Test case name and documentation</a></li>
-<li><a class="reference internal" href="#tagging-test-cases"
id="id190">2.2.3   Tagging test cases</a></li>
-<li><a class="reference internal" href="#test-setup-and-teardown"
id="id191">2.2.4   Test setup and teardown</a></li>
+<li><a class="reference internal"
href="#test-case-name-and-documentation"
id="id190">2.2.2   Test case name and documentation</a></li>
+<li><a class="reference internal" href="#tagging-test-cases"
id="id191">2.2.3   Tagging test cases</a></li>
+<li><a class="reference internal" href="#test-setup-and-teardown"
id="id192">2.2.4   Test setup and teardown</a></li>
</ul>
</div>
<div class="section" id="test-case-syntax">
-<h3><a class="toc-backref" href="#id184">2.2.1   Test
case syntax</a></h3>
+<h3><a class="toc-backref" href="#id185">2.2.1   Test
case syntax</a></h3>
<div class="section" id="basic-syntax">
-<h4><a class="toc-backref" href="#id185">Basic syntax</a></h4>
+<h4><a class="toc-backref" href="#id186">Basic syntax</a></h4>
<p>Test cases are constructed in test case tables from the available
keywords. Keywords can be imported from <a class="reference internal"
href="#using-test-libraries">test libraries</a> or <a class="reference
internal" href="#resource-files">resource
files</a>, or created in the <a class="reference internal"
href="#creating-user-keywords">keyword table</a> of the test case file
@@ -1764,7 +1764,7 @@
</table>
</div>
<div class="section" id="workflow-tests-vs-data-driven-tests">
-<h4><a class="toc-backref" href="#id186">Workflow tests vs.
data-driven tests</a></h4>
+<h4><a class="toc-backref" href="#id187">Workflow tests vs.
data-driven tests</a></h4>
<p>In general, there are two kinds of test cases. So called <em>workflow</em>
tests, such as the <span class="name">Valid Login</span> test above,
are constructed from
several keywords. Their normal structure is that first the system is
@@ -1839,7 +1839,7 @@
for <a class="reference internal" href="#escaping">escaping</a> empty
cells at the end of the table.</p>
</div>
<div class="section" id="settings-in-the-test-case-table">
-<h4><a class="toc-backref" href="#id187">Settings in the Test Case table</a></h4>
+<h4><a class="toc-backref" href="#id188">Settings in the Test Case table</a></h4>
<p>Test cases can also have their own settings. Setting names are always
in the second column, where keywords normally are, and their values
are in the subsequent columns. Setting names have square brackets around
@@ -1893,7 +1893,7 @@
</table>
</div>
<div class="section" id="test-case-related-settings-in-the-setting-table">
-<h4><a class="toc-backref" href="#id188">Test-case-related settings in
the Setting table</a></h4>
+<h4><a class="toc-backref" href="#id189">Test-case-related settings in
the Setting table</a></h4>
<p>The Setting table can have the following test-case-related
settings. These settings are mainly default values for the
test-case-specific settings listed earlier.</p>
@@ -1911,7 +1911,7 @@
</div>
</div>
<div class="section" id="test-case-name-and-documentation">
-<h3><a class="toc-backref" href="#id189">2.2.2   Test
case name and documentation</a></h3>
+<h3><a class="toc-backref" href="#id190">2.2.2   Test
case name and documentation</a></h3>
<p>The test case name comes directly from the Test Case table: it is
exactly what is entered into the test case column. Test cases in one
test suite should have unique names. Pertaining to this, you can also
@@ -1997,7 +1997,7 @@
better specified using <a class="reference internal" href="#tagging-test-cases">tags</a>.</p>
</div>
<div class="section" id="tagging-test-cases">
-<h3><a class="toc-backref"
href="#id190">2.2.3   Tagging test cases</a></h3>
+<h3><a class="toc-backref"
href="#id191">2.2.3   Tagging test cases</a></h3>
<p>Using tags in Robot Framework is a simple, yet powerful mechanism for
classifying test cases. Tags are free text and they can be used at
least for the following purposes:</p>
@@ -2174,7 +2174,7 @@
</table>
</div>
<div class="section" id="test-setup-and-teardown">
-<h3><a class="toc-backref" href="#id191">2.2.4   Test
setup and teardown</a></h3>
+<h3><a class="toc-backref" href="#id192">2.2.4   Test
setup and teardown</a></h3>
<p>Robot Framework has similar test setup and teardown functions as many
other test automation frameworks. In short, a test setup is something
that is executed before a test case and a test teardown is executed
@@ -2355,24 +2355,24 @@
</div>
</div>
<div class="section" id="creating-test-suites">
-<h2><a class="toc-backref" href="#id168">2.3   Creating
test suites</a></h2>
+<h2><a class="toc-backref" href="#id169">2.3   Creating
test suites</a></h2>
<p>Robot Framework test cases are created in test case files, which can
be organized into directories. These files and directories create a
hierarchical test suite structure.</p>
<div class="contents local topic" id="id18">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#test-case-files"
id="id192">2.3.1   Test case files</a></li>
-<li><a class="reference internal" href="#test-suite-directories"
id="id193">2.3.2   Test suite directories</a><ul>
-<li><a class="reference internal" href="#initialization-files"
id="id194">Initialization files</a></li>
+<li><a class="reference internal" href="#test-case-files"
id="id193">2.3.1   Test case files</a></li>
+<li><a class="reference internal" href="#test-suite-directories"
id="id194">2.3.2   Test suite directories</a><ul>
+<li><a class="reference internal" href="#initialization-files"
id="id195">Initialization files</a></li>
</ul>
</li>
-<li><a class="reference internal"
href="#test-suite-name-and-documentation"
id="id195">2.3.3   Test suite name and documentation</a></li>
-<li><a class="reference internal" href="#free-test-suite-metadata"
id="id196">2.3.4   Free test suite metadata</a></li>
-<li><a class="reference internal" href="#suite-setup-and-teardown"
id="id197">2.3.5   Suite setup and teardown</a></li>
+<li><a class="reference internal"
href="#test-suite-name-and-documentation"
id="id196">2.3.3   Test suite name and documentation</a></li>
+<li><a class="reference internal" href="#free-test-suite-metadata"
id="id197">2.3.4   Free test suite metadata</a></li>
+<li><a class="reference internal" href="#suite-setup-and-teardown"
id="id198">2.3.5   Suite setup and teardown</a></li>
</ul>
</div>
<div class="section" id="test-case-files">
-<h3><a class="toc-backref" href="#id192">2.3.1   Test
case files</a></h3>
+<h3><a class="toc-backref" href="#id193">2.3.1   Test
case files</a></h3>
<p>Robot Framework test cases <a class="reference internal"
href="#test-case-syntax">are created</a> using test case tables in
test case files. Such a file automatically creates a test suite from
all the test cases it contains. There is no upper limit for how many
@@ -2392,7 +2392,7 @@
</dl>
</div>
<div class="section" id="test-suite-directories">
-<h3><a class="toc-backref" href="#id193">2.3.2   Test
suite directories</a></h3>
+<h3><a class="toc-backref" href="#id194">2.3.2   Test
suite directories</a></h3>
<p>Test case files can be organized into directories, and these
directories create higher-level test suites. A test suite created from
a directory cannot have any test cases directly, but it contains
@@ -2416,7 +2416,7 @@
contain any test cases, they are silently ignored (a message is
written to the <a class="reference internal"
href="#system-log">syslog</a>) and the processing continues.</p>
<div class="section" id="initialization-files">
-<h4><a class="toc-backref" href="#id194">Initialization files</a></h4>
+<h4><a class="toc-backref" href="#id195">Initialization files</a></h4>
<p>A test suite created from a directory can have the same settings
(<span class="opt">Documentation</span>, <span class="opt">Meta:
<name></span>, <span class="opt">Suite
Setup</span>, <span class="opt">Suite Teardown</span>) as a test case
created from a
@@ -2519,7 +2519,7 @@
</div>
</div>
<div class="section" id="test-suite-name-and-documentation">
-<h3><a class="toc-backref" href="#id195">2.3.3   Test
suite name and documentation</a></h3>
+<h3><a class="toc-backref" href="#id196">2.3.3   Test
suite name and documentation</a></h3>
<p>The test suite name is got directly from the file or directory
name, but
a possible file extension is ignored. The name is created so that
underscores are replaced with spaces, words in camelCaseFormat
@@ -2566,7 +2566,7 @@
explained in section <a class="reference internal"
href="#setting-metadata">Setting metadata</a>.</p>
</div>
<div class="section" id="free-test-suite-metadata">
-<h3><a class="toc-backref" href="#id196">2.3.4   Free
test suite metadata</a></h3>
+<h3><a class="toc-backref" href="#id197">2.3.4   Free
test suite metadata</a></h3>
<p>Test suites can also have other metadata than the documentation. This
metadata is defined in the Setting table using the <span
class="opt">Meta: <name></span>
setting, where <name> is a freely selected metadata name. For example,
@@ -2615,7 +2615,7 @@
detail in section <a class="reference internal"
href="#setting-metadata">Setting metadata</a>.</p>
</div>
<div class="section" id="suite-setup-and-teardown">
-<h3><a class="toc-backref" href="#id197">2.3.5   Suite
setup and teardown</a></h3>
+<h3><a class="toc-backref" href="#id198">2.3.5   Suite
setup and teardown</a></h3>
<p>Not only <a class="reference internal"
href="#test-setup-and-teardown">test cases</a> but also test suites can
have a setup and
a teardown. A suite setup is executed before running any of the suite's
test cases or child test suites, and a test teardown is executed after
@@ -2644,7 +2644,7 @@
</div>
</div>
<div class="section" id="using-test-libraries">
-<h2><a class="toc-backref" href="#id169">2.4   Using
test libraries</a></h2>
+<h2><a class="toc-backref" href="#id170">2.4   Using
test libraries</a></h2>
<p>Test libraries contain those lowest-level keywords, often called
<em>library keywords</em>, which actually interact with the system under
test. All test cases always use keywords from some library, often
@@ -2654,30 +2654,31 @@
section.</p>
<div class="contents local topic" id="id23">
<ul class="auto-toc simple">
-<li><a class="reference internal"
href="#taking-test-libraries-into-use"
id="id198">2.4.1   Taking test libraries into use</a><ul>
-<li><a class="reference internal" href="#using-library-setting"
id="id199">Using Library setting</a></li>
-<li><a class="reference internal" href="#using-import-library-keyword"
id="id200">Using Import Library keyword</a></li>
-<li><a class="reference internal" href="#library-search-path"
id="id201">Library search path</a></li>
-</ul>
-</li>
-<li><a class="reference internal"
href="#setting-custom-name-to-test-library"
id="id202">2.4.2   Setting custom name to test library</a></li>
-<li><a class="reference internal" href="#standard-libraries"
id="id203">2.4.3   Standard libraries</a><ul>
-<li><a class="reference internal" href="#builtin-library"
id="id204">BuiltIn library</a></li>
-<li><a class="reference internal" href="#operatingsystem-library"
id="id205">OperatingSystem library</a></li>
-<li><a class="reference internal" href="#telnet-library"
id="id206">Telnet library</a></li>
-<li><a class="reference internal" href="#collections-library"
id="id207">Collections library</a></li>
-<li><a class="reference internal" href="#screenshot-library"
id="id208">Screenshot library</a></li>
+<li><a class="reference internal"
href="#taking-test-libraries-into-use"
id="id199">2.4.1   Taking test libraries into use</a><ul>
+<li><a class="reference internal" href="#using-library-setting"
id="id200">Using Library setting</a></li>
+<li><a class="reference internal" href="#using-import-library-keyword"
id="id201">Using Import Library keyword</a></li>
+<li><a class="reference internal" href="#library-search-path"
id="id202">Library search path</a></li>
+<li><a class="reference internal"
href="#using-physical-path-to-library" id="id203">Using physical path
to library</a></li>
+</ul>
+</li>
+<li><a class="reference internal"
href="#setting-custom-name-to-test-library"
id="id204">2.4.2   Setting custom name to test library</a></li>
+<li><a class="reference internal" href="#standard-libraries"
id="id205">2.4.3   Standard libraries</a><ul>
+<li><a class="reference internal" href="#builtin-library"
id="id206">BuiltIn library</a></li>
+<li><a class="reference internal" href="#operatingsystem-library"
id="id207">OperatingSystem library</a></li>
+<li><a class="reference internal" href="#telnet-library"
id="id208">Telnet library</a></li>
+<li><a class="reference internal" href="#collections-library"
id="id209">Collections library</a></li>
+<li><a class="reference internal" href="#screenshot-library"
id="id210">Screenshot library</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#external-libraries"
id="id209">2.4.4   External libraries</a></li>
+<li><a class="reference internal" href="#external-libraries"
id="id211">2.4.4   External libraries</a></li>
</ul>
</div>
<div class="section" id="taking-test-libraries-into-use">
-<h3><a class="toc-backref" href="#id198">2.4.1   Taking
test libraries into use</a></h3>
+<h3><a class="toc-backref" href="#id199">2.4.1   Taking
test libraries into use</a></h3>
<p>Instructions for taking test libraries into use are given in the
subsections below.</p>
<div class="section" id="using-library-setting">
-<h4><a class="toc-backref" href="#id199">Using Library setting</a></h4>
+<h4><a class="toc-backref" href="#id200">Using Library setting</a></h4>
<p>Test libraries are normally imported using the <span class="opt">Library</span>
setting in the Setting table and having the library name in the
subsequent column. The library name is case-sensitive (it is the name
@@ -2732,7 +2733,7 @@
files using them.</p>
</div>
<div class="section" id="using-import-library-keyword">
-<h4><a class="toc-backref" href="#id200">Using Import Library keyword</a></h4>
+<h4><a class="toc-backref" href="#id201">Using Import Library keyword</a></h4>
<p>Another possibility to take a test library into use is using the
keyword <span class="name">Import Library</span> from the <a
class="reference internal" href="#builtin-library">BuiltIn library</a>.
This keyword
takes the library name and possible arguments similarly as the
@@ -2781,18 +2782,82 @@
</table>
</div>
<div class="section" id="library-search-path">
-<h4><a class="toc-backref" href="#id201">Library search path</a></h4>
-<p>Robot Framework can import a library only if the library class or
-module can be found from the library search path. Basically, this
-means that the library code and all its possible dependencies must be
-in <span class="code">PYTHONPATH</span> or, when running tests on
Jython, in a
+<h4><a class="toc-backref" href="#id202">Library search path</a></h4>
+<p>The most common way to specify a test library to import is using its
+name, like it has been done in all the examples in this section. In
+these cases Robot Framework tries to find the class or module
+implementing the library from the <em>library search path</em>. Basically,
+this means that the library code and all its possible dependencies
+must be in <span class="code">PYTHONPATH</span> or, when running tests
on Jython, in a
<span class="code">CLASSPATH</span>. <a class="reference internal"
href="#adjusting-library-search-path">Setting the library search
path</a> is explained in
-a section of its own, and well-developed libraries either do that
-automatically or have clear instructions on how to do it.</p>
+a section of its own. Libraries can also set the search path
+automatically or have special instructions on how to do it. All
+<a class="reference internal" href="#standard-libraries">standard
libraries</a>, for example, are in the library search path
+automatically.</p>
+<p>The biggest benefit of this approach is that when the library search
+path has been configured, often using a <a class="reference internal"
href="#creating-start-up-scripts">custom start-up script</a>,
+normal users do not need to think where libraries actually are
+installed. The drawback is that getting your own, possible
+very simple, libraries into the search path may require some
+additional configuration.</p>
+</div>
+<div class="section" id="using-physical-path-to-library">
+<h4><a class="toc-backref" href="#id203">Using physical path to library</a></h4>
+<p>Another mechanism for specifying the library to import is using a
+path to it in the file system. This path is considered relative to the
+directory where current test data file is situated similarly as paths
+to <a class="reference internal"
href="#resource-and-variable-files">resource and variable files</a>.
The main benefit of this approach
+is that there is no need to configure the library search path.</p>
+<p>If the library is a file, the path to it must contain extension. For
+Python libraries the extension is naturally <span
class="path">.py</span> and for Java
+libraries it can either be <span class="path">.class</span> or <span
class="path">.java</span>, but the
+class file must always be available. If Python library is implemented
+as a directory, the path to it must have a trailing forward slash
+(<span class="path">/</span>). Importing Java libraries in JAR
packages is not possible
+using this mechanism. Following examples demonstrate these different
+usages.</p>
+<table border="1" class="example docutils">
+<caption>Importing test libraries using physical paths to them</caption>
+<colgroup>
+<col width="17%" />
+<col width="51%" />
+<col width="15%" />
+<col width="17%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">Setting</th>
+<th class="head">Value</th>
+<th class="head">Value</th>
+<th class="head">Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>Library</td>
+<td>PythonLib.py</td>
+<td></td>
+<td></td>
+</tr>
+<tr><td>Library</td>
+<td>/absolute/path/JavaLib.java</td>
+<td></td>
+<td></td>
+</tr>
+<tr><td>Library</td>
+<td>relative/path/PythonDirLib/</td>
+<td>possible</td>
+<td>arguments</td>
+</tr>
+<tr><td>Library</td>
+<td>${RESOURCES}/Example.class</td>
+<td></td>
+<td></td>
+</tr>
+</tbody>
+</table>
</div>
</div>
<div class="section" id="setting-custom-name-to-test-library">
-<h3><a class="toc-backref"
href="#id202">2.4.2   Setting custom name to test library</a></h3>
+<h3><a class="toc-backref"
href="#id204">2.4.2   Setting custom name to test library</a></h3>
<p>The library name is shown in test logs before keyword names, and if
multiple keywords have the same name, they must be used so that the
<a class="reference internal"
href="#handling-keywords-with-same-names">keyword name is prefixed with
the library name</a>. The library name
@@ -2917,7 +2982,7 @@
library in the Setting table and when using the <span
class="name">Import Library</span> keyword.</p>
</div>
<div class="section" id="standard-libraries">
-<h3><a class="toc-backref"
href="#id203">2.4.3   Standard libraries</a></h3>
+<h3><a class="toc-backref"
href="#id205">2.4.3   Standard libraries</a></h3>
<p>Some test libraries are distributed with Robot Framework and these
libraries are called <em>standard libraries</em>. These are the available
standard libraries:</p>
@@ -2944,7 +3009,7 @@
without any external dependencies, and is adequately tested and
documented.</p>
<div class="section" id="builtin-library">
-<h4><a class="toc-backref" href="#id204">BuiltIn library</a></h4>
+<h4><a class="toc-backref" href="#id206">BuiltIn library</a></h4>
<p>The BuiltIn library provides a set of generic keywords needed
often. The provided keywords allow functions for verifications (for
example, <span class="name">Should Be Equal</span>), conversions (for
example, <span class="name">Convert
@@ -2958,7 +3023,7 @@
<p>For more information, see the <a class="reference external"
href="../libraries/BuiltIn.html">BuiltIn library documentation</a>.</p>
</div>
<div class="section" id="operatingsystem-library">
-<h4><a class="toc-backref" href="#id205">OperatingSystem library</a></h4>
+<h4><a class="toc-backref" href="#id207">OperatingSystem library</a></h4>
<p>The OperatingSystem library enables various operating-system-related
tasks to be performed in the system running Robot Framework. It can,
among other things, execute commands (for example, <span
class="name">Run</span>) and
@@ -2974,7 +3039,7 @@
<p>For more information, see the <a class="reference external"
href="../libraries/OperatingSystem.html">OperatingSystem library documentation</a>.</p>
</div>
<div class="section" id="telnet-library">
-<h4><a class="toc-backref" href="#id206">Telnet library</a></h4>
+<h4><a class="toc-backref" href="#id208">Telnet library</a></h4>
<p>The Telnet library enables testing over a Telnet connection. It
has functions for logging into a Telnet server, running commands on
the server and returning the output. The Telnet library extends
@@ -2983,7 +3048,7 @@
<p>For more information, see the <a class="reference external"
href="../libraries/Telnet.html">Telnet library documentation</a>.</p>
</div>
<div class="section" id="collections-library">
-<h4><a class="toc-backref" href="#id207">Collections library</a></h4>
+<h4><a class="toc-backref" href="#id209">Collections library</a></h4>
<p>The Collections library provides a set of keywords for handling
Python's standard list and dictionary data structures. For more
information about lists and dictionaries, see <a class="reference
external" href="http://docs.python.org/lib/lib.html">Python Library
@@ -2995,7 +3060,7 @@
<p>For more information, see the <a class="reference external"
href="../libraries/Collections.html">Collections library documentation</a>.</p>
</div>
<div class="section" id="screenshot-library">
-<h4><a class="toc-backref" href="#id208">Screenshot library</a></h4>
+<h4><a class="toc-backref" href="#id210">Screenshot library</a></h4>
<p>The Screenshot library provides a way to capture and store screenshots
of the whole desktop. This library is implemented with Java AWT APIs,
so it can be used only when running Robot Framework with Jython.</p>
@@ -3003,7 +3068,7 @@
</div>
</div>
<div class="section" id="external-libraries">
-<h3><a class="toc-backref"
href="#id209">2.4.4   External libraries</a></h3>
+<h3><a class="toc-backref"
href="#id211">2.4.4   External libraries</a></h3>
<p>Any test library that is not one of the standard libraries is, by
definition, <em>an external library</em>. Robot Framework developers provide
some generic libraries, such as SeleniumLibrary, which are not
@@ -3018,40 +3083,40 @@
</div>
</div>
<div class="section" id="variables">
-<h2><a class="toc-backref" href="#id170">2.5   Variables</a></h2>
-<div class="contents local topic" id="id26">
+<h2><a class="toc-backref" href="#id171">2.5   Variables</a></h2>
+<div class="contents local topic" id="id27">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#id27" id="id210">2.5.1   Introduction</a></li>
-<li><a class="reference internal" href="#variable-types"
id="id211">2.5.2   Variable types</a><ul>
-<li><a class="reference internal" href="#scalar-variables"
id="id212">Scalar variables</a></li>
-<li><a class="reference internal" href="#list-variables"
id="id213">List variables</a></li>
-<li><a class="reference internal" href="#environment-variables"
id="id214">Environment variables</a></li>
+<li><a class="reference internal" href="#id28" id="id212">2.5.1   Introduction</a></li>
+<li><a class="reference internal" href="#variable-types"
id="id213">2.5.2   Variable types</a><ul>
+<li><a class="reference internal" href="#scalar-variables"
id="id214">Scalar variables</a></li>
+<li><a class="reference internal" href="#list-variables"
id="id215">List variables</a></li>
+<li><a class="reference internal" href="#environment-variables"
id="id216">Environment variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#creating-variables"
id="id215">2.5.3   Creating variables</a><ul>
-<li><a class="reference internal" href="#variable-table"
id="id216">Variable table</a></li>
-<li><a class="reference internal" href="#variable-file"
id="id217">Variable file</a></li>
-<li><a class="reference internal"
href="#setting-variables-in-command-line" id="id218">Setting variables
in command line</a></li>
-<li><a class="reference internal" href="#return-values-from-keywords"
id="id219">Return values from keywords</a></li>
-<li><a class="reference internal" href="#variable-scopes"
id="id220">Variable scopes</a></li>
+<li><a class="reference internal" href="#creating-variables"
id="id217">2.5.3   Creating variables</a><ul>
+<li><a class="reference internal" href="#variable-table"
id="id218">Variable table</a></li>
+<li><a class="reference internal" href="#variable-file"
id="id219">Variable file</a></li>
+<li><a class="reference internal"
href="#setting-variables-in-command-line" id="id220">Setting variables
in command line</a></li>
+<li><a class="reference internal" href="#return-values-from-keywords"
id="id221">Return values from keywords</a></li>
+<li><a class="reference internal" href="#variable-scopes"
id="id222">Variable scopes</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#built-in-variables"
id="id221">2.5.4   Built-in variables</a><ul>
-<li><a class="reference internal" href="#operating-system-variables"
id="id222">Operating-system variables</a></li>
-<li><a class="reference internal" href="#number-variables"
id="id223">Number variables</a></li>
-<li><a class="reference internal"
href="#boolean-and-none-null-variables" id="id224">Boolean and
None/null variables</a></li>
-<li><a class="reference internal" href="#automatic-variables"
id="id225">Automatic variables</a></li>
+<li><a class="reference internal" href="#built-in-variables"
id="id223">2.5.4   Built-in variables</a><ul>
+<li><a class="reference internal" href="#operating-system-variables"
id="id224">Operating-system variables</a></li>
+<li><a class="reference internal" href="#number-variables"
id="id225">Number variables</a></li>
+<li><a class="reference internal"
href="#boolean-and-none-null-variables" id="id226">Boolean and
None/null variables</a></li>
+<li><a class="reference internal" href="#automatic-variables"
id="id227">Automatic variables</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#advanced-variable-features"
id="id226">2.5.5   Advanced variable features</a><ul>
-<li><a class="reference internal" href="#extended-variable-syntax"
id="id227">Extended variable syntax</a></li>
-<li><a class="reference internal" href="#variables-inside-variables"
id="id228">Variables inside variables</a></li>
+<li><a class="reference internal" href="#advanced-variable-features"
id="id228">2.5.5   Advanced variable features</a><ul>
+<li><a class="reference internal" href="#extended-variable-syntax"
id="id229">Extended variable syntax</a></li>
+<li><a class="reference internal" href="#variables-inside-variables"
id="id230">Variables inside variables</a></li>
</ul>
</li>
</ul>
</div>
-<div class="section" id="id27">
-<h3><a class="toc-backref" href="#id210">2.5.1   Introduction</a></h3>
+<div class="section" id="id28">
+<h3><a class="toc-backref" href="#id212">2.5.1   Introduction</a></h3>
<p>Variables are an integral feature of Robot Framework, and they can be
used in most places in test data. Most commonly, they are used in
arguments for keywords in test case tables and keyword tables, but
@@ -3090,7 +3155,7 @@
literal string, it must be <a class="reference internal"
href="#escaping">escaped with a backslash</a> as in <span class="code">\${NAME}</span>.</p>
</div>
<div class="section" id="variable-types">
-<h3><a class="toc-backref"
href="#id211">2.5.2   Variable types</a></h3>
+<h3><a class="toc-backref"
href="#id213">2.5.2   Variable types</a></h3>
<p>Different variable types are briefly described in this section. The
creation and usage of variables is described in more detail in the
following subsections.</p>
@@ -3109,7 +3174,7 @@
numbers (from 0 to 9), underscore and space is recommended, and it is
even a requirement for using <a class="reference internal"
href="#extended-variable-syntax">extended variable syntax</a>.</p>
<div class="section" id="scalar-variables">
-<h4><a class="toc-backref" href="#id212">Scalar variables</a></h4>
+<h4><a class="toc-backref" href="#id214">Scalar variables</a></h4>
<p>When scalar variables are used in the test data, they are replaced
with the value they are assigned to. While scalar variables are most
commonly used for simple strings, you can assign any objects,
@@ -3227,7 +3292,7 @@
</ul>
</div>
<div class="section" id="list-variables">
-<h4><a class="toc-backref" href="#id213">List variables</a></h4>
+<h4><a class="toc-backref" href="#id215">List variables</a></h4>
<p>List variables are compound variables that can have several
values assigned to them. In short, they are always lists and can
contain an unlimited number of entries (also empty lists are
@@ -3317,7 +3382,7 @@
</table>
</div>
<div class="section" id="environment-variables">
-<h4><a class="toc-backref" href="#id214">Environment variables</a></h4>
+<h4><a class="toc-backref" href="#id216">Environment variables</a></h4>
<p>Robot Framework allows using environment variables in the test
data using the syntax <span class="var">%{ENV_VAR_NAME}</span>. They
are limited to string
values.</p>
@@ -3360,11 +3425,11 @@
</div>
</div>
<div class="section" id="creating-variables">
-<h3><a class="toc-backref"
href="#id215">2.5.3   Creating variables</a></h3>
+<h3><a class="toc-backref"
href="#id217">2.5.3   Creating variables</a></h3>
<p>Variables can spring into existence from different sources as
described in the subsections below.</p>
<div class="section" id="variable-table">
-<h4><a class="toc-backref" href="#id216">Variable table</a></h4>
+<h4><a class="toc-backref" href="#id218">Variable table</a></h4>
<p>The most common source for variables are Variable tables in test case
files and resource files. Variable tables are convenient, because they
allow creating variables in the same place as the rest of the test
@@ -3497,7 +3562,7 @@
</div>
</div>
<div class="section" id="variable-file">
-<h4><a class="toc-backref" href="#id217">Variable file</a></h4>
+<h4><a class="toc-backref" href="#id219">Variable file</a></h4>
<p>Variable files are the most powerful mechanism for creating different
kind of variables. It is possible to assign variables to any object
using them, and they also enable creating variables dynamically. The
@@ -3505,7 +3570,7 @@
in section <a class="reference internal"
href="#resource-and-variable-files">Resource and variable files</a>.</p>
</div>
<div class="section" id="setting-variables-in-command-line">
-<h4><a class="toc-backref" href="#id218">Setting variables in command line</a></h4>
+<h4><a class="toc-backref" href="#id220">Setting variables in command line</a></h4>
<p>Variables can be set from the command line either individually with
the <span class="opt">--variable</span> option or using a variable
file with the
<span class="opt">--variablefile</span> option. Variables set from the
command line
@@ -3539,7 +3604,7 @@
name in the variable files.</p>
</div>
<div class="section" id="return-values-from-keywords">
-<h4><a class="toc-backref" href="#id219">Return values from keywords</a></h4>
+<h4><a class="toc-backref" href="#id221">Return values from keywords</a></h4>
<p>Return values from keywords can also be set into variables. This
allows communication between different keywords even in different test
libraries. The syntax for a simple case is illustrated in the example below:</p>
@@ -3650,7 +3715,7 @@
available from the <a class="reference internal"
href="#builtin-library">BuiltIn library</a>.</p>
</div>
<div class="section" id="variable-scopes">
-<h4><a class="toc-backref" href="#id220">Variable scopes</a></h4>
+<h4><a class="toc-backref" href="#id222">Variable scopes</a></h4>
<p>Depending on where and how they are created, variables can have a
global, test suite, test case or user keyword scope.</p>
<div class="section" id="global-scope">
@@ -3698,11 +3763,11 @@
</div>
</div>
<div class="section" id="built-in-variables">
-<h3><a class="toc-backref"
href="#id221">2.5.4   Built-in variables</a></h3>
+<h3><a class="toc-backref"
href="#id223">2.5.4   Built-in variables</a></h3>
<p>Robot Framework provides some built-in variables that are available
automatically.</p>
<div class="section" id="operating-system-variables">
-<h4><a class="toc-backref" href="#id222">Operating-system variables</a></h4>
+<h4><a class="toc-backref" href="#id224">Operating-system variables</a></h4>
<p>Built-in variables related to the operating system ease making the
test data
operating-system-agnostic.</p>
<table border="1" class="tabular docutils">
@@ -3766,7 +3831,7 @@
</table>
</div>
<div class="section" id="number-variables">
-<h4><a class="toc-backref" href="#id223">Number variables</a></h4>
+<h4><a class="toc-backref" href="#id225">Number variables</a></h4>
<p>The variable syntax can be used for creating both integers and
floating point numbers, as illustrated in the example below. This is
useful when a keyword expects to get a real number as an argument.</p>
@@ -3810,7 +3875,7 @@
</table>
</div>
<div class="section" id="boolean-and-none-null-variables">
-<h4><a class="toc-backref" href="#id224">Boolean and None/null variables</a></h4>
+<h4><a class="toc-backref" href="#id226">Boolean and None/null variables</a></h4>
<p>Also Boolean values and Python <span class="code">None</span> and
Java <span class="code">null</span> can
be created using the variable syntax similarly as numbers.</p>
<table border="1" class="example docutils">
@@ -3870,7 +3935,7 @@
<span class="code">null</span> to the correct format when necessary.</p>
</div>
<div class="section" id="automatic-variables">
-<h4><a class="toc-backref" href="#id225">Automatic variables</a></h4>
+<h4><a class="toc-backref" href="#id227">Automatic variables</a></h4>
<p>Some automatic variables can also be used in the test data. These
variables can have different values during the test execution and some
of them are not even available all the time.</p>
@@ -3971,10 +4036,10 @@
</div>
</div>
<div class="section" id="advanced-variable-features">
-<h3><a class="toc-backref"
href="#id226">2.5.5   Advanced variable features</a></h3>
+<h3><a class="toc-backref"
href="#id228">2.5.5   Advanced variable features</a></h3>
<p>There are also some advanced variable features, described in this section.</p>
<div class="section" id="extended-variable-syntax">
-<h4><a class="toc-backref" href="#id227">Extended variable syntax</a></h4>
+<h4><a class="toc-backref" href="#id229">Extended variable syntax</a></h4>
<p>Extended variable syntax can be used with objects set into scalar
variables. This allows accessing the attributes of the object (for example,
<span class="var">${obj.name}</span> or <span
class="var">${obj.some_attr}</span>), and even calling
@@ -4093,7 +4158,7 @@
</pre></div>
</div>
<div class="section" id="variables-inside-variables">
-<h4><a class="toc-backref" href="#id228">Variables inside variables</a></h4>
+<h4><a class="toc-backref" href="#id230">Variables inside variables</a></h4>
<p>Variables are allowed also inside variables, and when this syntax is
used, variables are resolved from the inside out. For example, if you
have a variable <span class="var">${var${x}}</span>, then <span
class="var">${x}</span> is resolved
@@ -4164,33 +4229,33 @@
</div>
</div>
<div class="section" id="creating-user-keywords">
-<h2><a class="toc-backref" href="#id171">2.6   Creating
user keywords</a></h2>
+<h2><a class="toc-backref" href="#id172">2.6   Creating
user keywords</a></h2>
<p>Keyword tables are used to create new higher-level keywords by
combining existing
keywords together. These keywords are called <em>user keywords</em> to
differentiate them
from lowest level <em>library keywords</em> that are implemented in
test libraries. The
syntax for creating user keywords is very close to the
syntax for creating test cases, which makes it easy to learn.</p>
-<div class="contents local topic" id="id32">
+<div class="contents local topic" id="id33">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#user-keyword-syntax"
id="id229">2.6.1   User keyword syntax</a><ul>
-<li><a class="reference internal" href="#id33" id="id230">Basic syntax</a></li>
-<li><a class="reference internal"
href="#settings-in-the-keyword-table" id="id231">Settings in the
Keyword table</a></li>
+<li><a class="reference internal" href="#user-keyword-syntax"
id="id231">2.6.1   User keyword syntax</a><ul>
+<li><a class="reference internal" href="#id34" id="id232">Basic syntax</a></li>
+<li><a class="reference internal"
href="#settings-in-the-keyword-table" id="id233">Settings in the
Keyword table</a></li>
</ul>
</li>
-<li><a class="reference internal"
href="#user-keyword-name-and-documentation"
id="id232">2.6.2   User keyword name and documentation</a></li>
-<li><a class="reference internal" href="#user-keyword-arguments"
id="id233">2.6.3   User keyword arguments</a><ul>
-<li><a class="reference internal" href="#positional-arguments"
id="id234">Positional arguments</a></li>
-<li><a class="reference internal" href="#default-values"
id="id235">Default values</a></li>
-<li><a class="reference internal" href="#variable-number-of-arguments"
id="id236">Variable number of arguments</a></li>
+<li><a class="reference internal"
href="#user-keyword-name-and-documentation"
id="id234">2.6.2   User keyword name and documentation</a></li>
+<li><a class="reference internal" href="#user-keyword-arguments"
id="id235">2.6.3   User keyword arguments</a><ul>
+<li><a class="reference internal" href="#positional-arguments"
id="id236">Positional arguments</a></li>
+<li><a class="reference internal" href="#default-values"
id="id237">Default values</a></li>
+<li><a class="reference internal" href="#variable-number-of-arguments"
id="id238">Variable number of arguments</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#user-keyword-return-values"
id="id237">2.6.4   User keyword return values</a></li>
+<li><a class="reference internal" href="#user-keyword-return-values"
id="id239">2.6.4   User keyword return values</a></li>
</ul>
</div>
<div class="section" id="user-keyword-syntax">
-<h3><a class="toc-backref" href="#id229">2.6.1   User
keyword syntax</a></h3>
-<div class="section" id="id33">
-<h4><a class="toc-backref" href="#id230">Basic syntax</a></h4>
+<h3><a class="toc-backref" href="#id231">2.6.1   User
keyword syntax</a></h3>
+<div class="section" id="id34">
+<h4><a class="toc-backref" href="#id232">Basic syntax</a></h4>
<p>In many ways, the overall user keyword syntax is identical to the
<a class="reference internal" href="#test-case-syntax">test case
syntax</a>. User keywords are created in keyword tables
which differ from test case tables only by the name that is used to
@@ -4257,7 +4322,7 @@
only available in the files where they are created.</p>
</div>
<div class="section" id="settings-in-the-keyword-table">
-<h4><a class="toc-backref" href="#id231">Settings in the Keyword table</a></h4>
+<h4><a class="toc-backref" href="#id233">Settings in the Keyword table</a></h4>
<p>User keywords can have similar settings as <a class="reference
internal" href="#settings-in-the-test-case-table">test cases</a>, and they
have the same square bracket syntax separating them from keyword
names. All available settings are listed below and explained later in
@@ -4278,7 +4343,7 @@
</div>
</div>
<div class="section" id="user-keyword-name-and-documentation">
-<h3><a class="toc-backref" href="#id232">2.6.2   User
keyword name and documentation</a></h3>
+<h3><a class="toc-backref" href="#id234">2.6.2   User
keyword name and documentation</a></h3>
<p>The user keyword name is defined in the first column of the user
keyword table. Of course, the name should be descriptive, and it is
acceptable to have quite long keyword names. Actually, when creating
@@ -4293,7 +4358,7 @@
sequence, is shown as a keyword documentation in test logs.</p>
</div>
<div class="section" id="user-keyword-arguments">
-<h3><a class="toc-backref" href="#id233">2.6.3   User
keyword arguments</a></h3>
+<h3><a class="toc-backref" href="#id235">2.6.3   User
keyword arguments</a></h3>
<p>Most user keywords need to take some arguments. The syntax for
specifying them is probably the most complicated feature normally
needed with Robot Framework, but even that is relatively easy,
@@ -4301,7 +4366,7 @@
the <span class="opt">[Arguments]</span> setting, and argument names
use the same
syntax as <a class="reference internal"
href="#variables">variables</a>, for example <span class="var">${arg}</span>.</p>
<div class="section" id="positional-arguments">
-<h4><a class="toc-backref" href="#id234">Positional arguments</a></h4>
+<h4><a class="toc-backref" href="#id236">Positional arguments</a></h4>
<p>The simplest way to specify arguments (apart from not having them
at all)
is using only positional arguments. In most cases, this is all
that is needed.</p>
@@ -4377,7 +4442,7 @@
</table>
</div>
<div class="section" id="default-values">
-<h4><a class="toc-backref" href="#id235">Default values</a></h4>
+<h4><a class="toc-backref" href="#id237">Default values</a></h4>
<p>Positional arguments are probably sufficient in most
situations. However, sometimes it is useful to be able to have a
keyword that takes a different number of arguments and has default
@@ -4475,7 +4540,7 @@
is heavily inspired by Python syntax for function default values.</p>
</div>
<div class="section" id="variable-number-of-arguments">
-<h4><a class="toc-backref" href="#id236">Variable number of arguments</a></h4>
+<h4><a class="toc-backref" href="#id238">Variable number of arguments</a></h4>
<p>Sometimes, but more and more seldom, even default values are not
enough and there is a need for a keyword accepting any number of
arguments. User keywords support also this. All that is needed is
@@ -4586,7 +4651,7 @@
</div>
</div>
<div class="section" id="user-keyword-return-values">
-<h3><a class="toc-backref" href="#id237">2.6.4   User
keyword return values</a></h3>
+<h3><a class="toc-backref" href="#id239">2.6.4   User
keyword return values</a></h3>
<p>Similarly as library keywords, also user keywords can return
values. Return values are defined with the <span class="opt">[Return]</span>
setting. The values can then be <a class="reference internal"
href="#return-values-from-keywords">assigned to variables</a> in test
@@ -4713,7 +4778,7 @@
</div>
</div>
<div class="section" id="resource-and-variable-files">
-<h2><a class="toc-backref" href="#id172">2.7   Resource
and variable files</a></h2>
+<h2><a class="toc-backref" href="#id173">2.7   Resource
and variable files</a></h2>
<p>User keywords and variables in <a class="reference internal"
href="#test-case-files">test case files</a> and <a class="reference
internal" href="#initialization-files">test suite
initialization files</a> can only be used in files where they are
created, but <em>resource files</em> provide a mechanism for sharing
them. Since
@@ -4724,25 +4789,25 @@
enable creating variables dynamically. Their flexibility comes from
the fact that they are created using Python code, which also makes
them somewhat more complicated than Variable tables.</p>
-<div class="contents local topic" id="id38">
+<div class="contents local topic" id="id39">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#resource-files"
id="id238">2.7.1   Resource files</a><ul>
-<li><a class="reference internal"
href="#taking-resource-files-into-use" id="id239">Taking resource files
into use</a></li>
-<li><a class="reference internal" href="#resource-file-structure"
id="id240">Resource file structure</a></li>
+<li><a class="reference internal" href="#resource-files"
id="id240">2.7.1   Resource files</a><ul>
+<li><a class="reference internal"
href="#taking-resource-files-into-use" id="id241">Taking resource files
into use</a></li>
+<li><a class="reference internal" href="#resource-file-structure"
id="id242">Resource file structure</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#variable-files"
id="id241">2.7.2   Variable files</a><ul>
-<li><a class="reference internal"
href="#taking-variable-files-into-use" id="id242">Taking variable files
into use</a></li>
-<li><a class="reference internal" href="#creating-variables-directly"
id="id243">Creating variables directly</a></li>
-<li><a class="reference internal"
href="#getting-variables-from-a-special-function" id="id244">Getting
variables from a special function</a></li>
+<li><a class="reference internal" href="#variable-files"
id="id243">2.7.2   Variable files</a><ul>
+<li><a class="reference internal"
href="#taking-variable-files-into-use" id="id244">Taking variable files
into use</a></li>
+<li><a class="reference internal" href="#creating-variables-directly"
id="id245">Creating variables directly</a></li>
+<li><a class="reference internal"
href="#getting-variables-from-a-special-function" id="id246">Getting
variables from a special function</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="resource-files">
-<h3><a class="toc-backref"
href="#id238">2.7.1   Resource files</a></h3>
+<h3><a class="toc-backref"
href="#id240">2.7.1   Resource files</a></h3>
<div class="section" id="taking-resource-files-into-use">
-<h4><a class="toc-backref" href="#id239">Taking resource files into use</a></h4>
+<h4><a class="toc-backref" href="#id241">Taking resource files into use</a></h4>
<p>Resource files are imported using the <span
class="opt">Resource</span> setting in the
Settings table. The path to the resource file is given in the cell
after the setting name.</p>
@@ -4789,7 +4854,7 @@
resource file.</p>
</div>
<div class="section" id="resource-file-structure">
-<h4><a class="toc-backref" href="#id240">Resource file structure</a></h4>
+<h4><a class="toc-backref" href="#id242">Resource file structure</a></h4>
<p>The higher-level structure of resource files is the same as that of
test case files otherwise, but, of course, they cannot contain Test Case
tables. Additionally, the Setting table in resource files can contain
@@ -4937,7 +5002,7 @@
</div>
</div>
<div class="section" id="variable-files">
-<h3><a class="toc-backref"
href="#id241">2.7.2   Variable files</a></h3>
+<h3><a class="toc-backref"
href="#id243">2.7.2   Variable files</a></h3>
<p>Variable files contain <a class="reference internal"
href="#variables">variables</a> that can be used in test
data. Variables can also be created using variable tables or set from
the command line, but variable files allow creating them dynamically
@@ -4958,7 +5023,7 @@
approach quite flexible.</dd>
</dl>
<div class="section" id="taking-variable-files-into-use">
-<h4><a class="toc-backref" href="#id242">Taking variable files into use</a></h4>
+<h4><a class="toc-backref" href="#id244">Taking variable files into use</a></h4>
<div class="section" id="setting-table">
<h5>Setting table</h5>
<p>All test data files can import variables using the
@@ -5027,8 +5092,8 @@
</div>
</div>
<div class="section" id="creating-variables-directly">
-<h4><a class="toc-backref" href="#id243">Creating variables directly</a></h4>
-<div class="section" id="id41">
+<h4><a class="toc-backref" href="#id245">Creating variables directly</a></h4>
+<div class="section" id="id42">
<h5>Basic syntax</h5>
<p>When variable files are taken into use, they are imported as Python
modules and all their global attributes that do not start with an
@@ -5221,7 +5286,7 @@
</div>
</div>
<div class="section" id="getting-variables-from-a-special-function">
-<h4><a class="toc-backref" href="#id244">Getting variables from a
special function</a></h4>
+<h4><a class="toc-backref" href="#id246">Getting variables from a
special function</a></h4>
<p>An alternative syntax for getting variables is having a special
<span class="code">get_variables</span> function (also camelCase syntax
<span class="code">getVariables</span> is possible) in the variable
file. In this case,
@@ -5268,31 +5333,31 @@
</div>
</div>
<div class="section" id="advanced-features">
-<h2><a class="toc-backref" href="#id173">2.8   Advanced features</a></h2>
-<div class="contents local topic" id="id42">
+<h2><a class="toc-backref" href="#id174">2.8   Advanced features</a></h2>
+<div class="contents local topic" id="id43">
<ul class="auto-toc simple">
-<li><a class="reference internal"
href="#handling-keywords-with-same-names"
id="id245">2.8.1   Handling keywords with same names</a><ul>
-<li><a class="reference internal" href="#keyword-scopes"
id="id246">Keyword scopes</a></li>
-<li><a class="reference internal"
href="#specifying-a-keyword-explicitly" id="id247">Specifying a keyword explicitly</a></li>
+<li><a class="reference internal"
href="#handling-keywords-with-same-names"
id="id247">2.8.1   Handling keywords with same names</a><ul>
+<li><a class="reference internal" href="#keyword-scopes"
id="id248">Keyword scopes</a></li>
+<li><a class="reference internal"
href="#specifying-a-keyword-explicitly" id="id249">Specifying a keyword explicitly</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#timeouts" id="id248">2.8.2   Timeouts</a><ul>
-<li><a class="reference internal" href="#test-case-timeout"
id="id249">Test case timeout</a></li>
-<li><a class="reference internal" href="#user-keyword-timeout"
id="id250">User keyword timeout</a></li>
+<li><a class="reference internal" href="#timeouts" id="id250">2.8.2   Timeouts</a><ul>
+<li><a class="reference internal" href="#test-case-timeout"
id="id251">Test case timeout</a></li>
+<li><a class="reference internal" href="#user-keyword-timeout"
id="id252">User keyword timeout</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#for-loops"
id="id251">2.8.3   For loops</a><ul>
-<li><a class="reference internal" href="#normal-for-loop"
id="id252">Normal for loop</a></li>
-<li><a class="reference internal" href="#using-several-loop-variables"
id="id253">Using several loop variables</a></li>
-<li><a class="reference internal" href="#for-in-range" id="id254">For
in range</a></li>
+<li><a class="reference internal" href="#for-loops"
id="id253">2.8.3   For loops</a><ul>
+<li><a class="reference internal" href="#normal-for-loop"
id="id254">Normal for loop</a></li>
+<li><a class="reference internal" href="#using-several-loop-variables"
id="id255">Using several loop variables</a></li>
+<li><a class="reference internal" href="#for-in-range" id="id256">For
in range</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#conditional-execution"
id="id255">2.8.4   Conditional execution</a></li>
-<li><a class="reference internal"
href="#parallel-execution-of-keywords"
id="id256">2.8.5   Parallel execution of keywords</a></li>
+<li><a class="reference internal" href="#conditional-execution"
id="id257">2.8.4   Conditional execution</a></li>
+<li><a class="reference internal"
href="#parallel-execution-of-keywords"
id="id258">2.8.5   Parallel execution of keywords</a></li>
</ul>
</div>
<div class="section" id="handling-keywords-with-same-names">
-<h3><a class="toc-backref"
href="#id245">2.8.1   Handling keywords with same names</a></h3>
+<h3><a class="toc-backref"
href="#id247">2.8.1   Handling keywords with same names</a></h3>
<p>Keywords that are used with Robot Framework are either <a
class="reference internal" href="#using-test-libraries">library
keywords</a> or <a class="reference internal"
href="#creating-user-keywords">user keywords</a>. The former come from
<a class="reference internal" href="#standard-libraries">standard
libraries</a> or <a class="reference internal"
href="#external-libraries">external libraries</a>, and the latter are either
@@ -5301,7 +5366,7 @@
that some of them have the same name, and this section describes how to
handle possible conflicts in these situations.</p>
<div class="section" id="keyword-scopes">
-<h4><a class="toc-backref" href="#id246">Keyword scopes</a></h4>
+<h4><a class="toc-backref" href="#id248">Keyword scopes</a></h4>
<p>When only a keyword name is used and there are several keywords with
that name, Robot Framework attempts to determine which keyword has the
highest priority based on its scope. The keyword's scope is determined
@@ -5322,7 +5387,7 @@
</ol>
</div>
<div class="section" id="specifying-a-keyword-explicitly">
-<h4><a class="toc-backref" href="#id247">Specifying a keyword explicitly</a></h4>
+<h4><a class="toc-backref" href="#id249">Specifying a keyword explicitly</a></h4>
<p>Scopes alone are not a sufficient solution, because there can be
keywords with the same name in several libraries or resources, and
additionally, they provide a mechanism to use only the keyword of the
@@ -5350,7 +5415,7 @@
</div>
</div>
<div class="section" id="timeouts">
-<h3><a class="toc-backref" href="#id248">2.8.2   Timeouts</a></h3>
+<h3><a class="toc-backref" href="#id250">2.8.2   Timeouts</a></h3>
<p>Keywords may be problematic in situations where they take
exceptionally long to execute or just hang endlessly. Robot Framework
allows you to set timeouts both for <a class="reference internal"
href="#creating-test-cases">test cases</a> and <a class="reference
internal" href="#creating-user-keywords">user
@@ -5369,7 +5434,7 @@
removed and keywords are always stopped.</p>
</div>
<div class="section" id="test-case-timeout">
-<h4><a class="toc-backref" href="#id249">Test case timeout</a></h4>
+<h4><a class="toc-backref" href="#id251">Test case timeout</a></h4>
<p>The test case timeout can be set either by using the <span class="opt">Test
Timeout</span> setting in the Setting table or the <span class="opt">[Timeout]</span>
setting in the Test Case table. <span class="opt">Test Timeout</span>
in the Setting
@@ -5548,7 +5613,7 @@
</table>
</div>
<div class="section" id="user-keyword-timeout">
-<h4><a class="toc-backref" href="#id250">User keyword timeout</a></h4>
+<h4><a class="toc-backref" href="#id252">User keyword timeout</a></h4>
<p>A timeout can be set for a user keyword using the <span class="opt">[Timeout]</span>
setting in the Keyword table. The syntax for setting it, including how
timeout values and possible custom messages are given, is
@@ -5629,7 +5694,7 @@
</div>
</div>
<div class="section" id="for-loops">
-<h3><a class="toc-backref" href="#id251">2.8.3   For loops</a></h3>
+<h3><a class="toc-backref" href="#id253">2.8.3   For loops</a></h3>
<p>Repeating same actions several times is quite a common need in test
automation. With Robot Framework, test libraries can have any kind of
loop constructs, and most of the time loops should be implemented in
@@ -5642,7 +5707,7 @@
<span class="code">FOR item IN sequence</span>, is derived from
Python, but similar
syntax is possible also in shell scripts or Perl.</p>
<div class="section" id="normal-for-loop">
-<h4><a class="toc-backref" href="#id252">Normal for loop</a></h4>
+<h4><a class="toc-backref" href="#id254">Normal for loop</a></h4>
<p>In a normal For loop, one variable is assigned into a list of values,
one value per iteration. The syntax starts with <span
class="name">:FOR</span>, where
colon is required to separate the syntax from normal keywords. The
@@ -5785,7 +5850,7 @@
</table>
</div>
<div class="section" id="using-several-loop-variables">
-<h4><a class="toc-backref" href="#id253">Using several loop variables</a></h4>
+<h4><a class="toc-backref" href="#id255">Using several loop variables</a></h4>
<p>It is also possible to use several loop variables. The syntax is the
same as with the normal For loop, but all loop variables are listed in
the cells between <span class="name">:FOR</span> and <span
class="name">IN</span>. There can be any number of loop
@@ -5875,7 +5940,7 @@
</table>
</div>
<div class="section" id="for-in-range">
-<h4><a class="toc-backref" href="#id254">For in range</a></h4>
+<h4><a class="toc-backref" href="#id256">For in range</a></h4>
<p>Earlier For loops always iterated over a sequence, and this is also
the most
common use case. Sometimes it is still convenient to have a For loop
that is executed a certain number of times, and Robot Framework has a
@@ -6041,7 +6106,7 @@
</div>
</div>
<div class="section" id="conditional-execution">
-<h3><a class="toc-backref"
href="#id255">2.8.4   Conditional execution</a></h3>
+<h3><a class="toc-backref"
href="#id257">2.8.4   Conditional execution</a></h3>
<p>In general, it is not recommended to have conditional logic in test
cases, or even in user keywords, because it can make them hard to
understand and maintain. Instead, this kind of logic should be in test
@@ -6070,7 +6135,7 @@
</ul>
</div>
<div class="section" id="parallel-execution-of-keywords">
-<h3><a class="toc-backref"
href="#id256">2.8.5   Parallel execution of keywords</a></h3>
+<h3><a class="toc-backref"
href="#id258">2.8.5   Parallel execution of keywords</a></h3>
<p>By default, all keywords are executed sequentially, so that a new
keyword is started only after the previous one has ended. Of course,
it is possible to create a library so that some keyword starts an
@@ -6193,48 +6258,48 @@
</div>
</div>
<div class="section" id="executing-test-cases">
-<h1><a class="toc-backref" href="#id132">3   Executing
test cases</a></h1>
-<div class="contents local topic" id="id46">
+<h1><a class="toc-backref" href="#id133">3   Executing
test cases</a></h1>
+<div class="contents local topic" id="id47">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#basic-usage"
id="id257">3.1   Basic usage</a></li>
-<li><a class="reference internal" href="#configuring-execution"
id="id258">3.2   Configuring execution</a></li>
-<li><a class="reference internal" href="#created-outputs"
id="id259">3.3   Created outputs</a></li>
+<li><a class="reference internal" href="#basic-usage"
id="id259">3.1   Basic usage</a></li>
+<li><a class="reference internal" href="#configuring-execution"
id="id260">3.2   Configuring execution</a></li>
+<li><a class="reference internal" href="#created-outputs"
id="id261">3.3   Created outputs</a></li>
</ul>
</div>
<div class="section" id="basic-usage">
-<h2><a class="toc-backref" href="#id257">3.1   Basic usage</a></h2>
+<h2><a class="toc-backref" href="#id259">3.1   Basic usage</a></h2>
<p>Robot Framework test cases are executed from the command line, and the
end result is, by default, an output file in the XML format and an HTML
report and log. After the execution, output files can be combined and
otherwise post-processed with the <span class="prog">rebot</span> tool.</p>
-<div class="contents local topic" id="id47">
+<div class="contents local topic" id="id48">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#starting-test-execution"
id="id260">3.1.1   Starting test execution</a><ul>
-<li><a class="reference internal" href="#different-runner-scripts"
id="id261">Different runner scripts</a></li>
-<li><a class="reference internal"
href="#specifying-the-test-data-to-be-executed" id="id262">Specifying
the test data to be executed</a></li>
-<li><a class="reference internal" href="#using-command-line-options"
id="id263">Using command line options</a></li>
-<li><a class="reference internal" href="#generated-outputs"
id="id264">Generated outputs</a></li>
-<li><a class="reference internal" href="#return-codes"
id="id265">Return codes</a></li>
+<li><a class="reference internal" href="#starting-test-execution"
id="id262">3.1.1   Starting test execution</a><ul>
+<li><a class="reference internal" href="#different-runner-scripts"
id="id263">Different runner scripts</a></li>
+<li><a class="reference internal"
href="#specifying-the-test-data-to-be-executed" id="id264">Specifying
the test data to be executed</a></li>
+<li><a class="reference internal" href="#using-command-line-options"
id="id265">Using command line options</a></li>
+<li><a class="reference internal" href="#generated-outputs"
id="id266">Generated outputs</a></li>
+<li><a class="reference internal" href="#return-codes"
id="id267">Return codes</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#post-processing-outputs"
id="id266">3.1.2   Post-processing outputs</a><ul>
-<li><a class="reference internal"
href="#creating-different-reports-and-logs" id="id267">Creating
different reports and logs</a></li>
-<li><a class="reference internal" href="#combining-outputs"
id="id268">Combining outputs</a></li>
+<li><a class="reference internal" href="#post-processing-outputs"
id="id268">3.1.2   Post-processing outputs</a><ul>
+<li><a class="reference internal"
href="#creating-different-reports-and-logs" id="id269">Creating
different reports and logs</a></li>
+<li><a class="reference internal" href="#combining-outputs"
id="id270">Combining outputs</a></li>
</ul>
</li>
-<li><a class="reference internal"
href="#getting-help-on-the-command-line"
id="id269">3.1.3   Getting help on the command line</a></li>
-<li><a class="reference internal"
href="#handling-complicated-characters"
id="id270">3.1.4   Handling complicated characters</a><ul>
-<li><a class="reference internal" href="#escaping-options"
id="id271">Escaping options</a></li>
-<li><a class="reference internal" href="#using-argument-files"
id="id272">Using argument files</a></li>
+<li><a class="reference internal"
href="#getting-help-on-the-command-line"
id="id271">3.1.3   Getting help on the command line</a></li>
+<li><a class="reference internal"
href="#handling-complicated-characters"
id="id272">3.1.4   Handling complicated characters</a><ul>
+<li><a class="reference internal" href="#escaping-options"
id="id273">Escaping options</a></li>
+<li><a class="reference internal" href="#using-argument-files"
id="id274">Using argument files</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#creating-start-up-scripts"
id="id273">3.1.5   Creating start-up scripts</a></li>
+<li><a class="reference internal" href="#creating-start-up-scripts"
id="id275">3.1.5   Creating start-up scripts</a></li>
</ul>
</div>
<div class="section" id="starting-test-execution">
-<h3><a class="toc-backref"
href="#id260">3.1.1   Starting test execution</a></h3>
+<h3><a class="toc-backref"
href="#id262">3.1.1   Starting test execution</a></h3>
<div class="section" id="different-runner-scripts">
-<h4><a class="toc-backref" href="#id261">Different runner scripts</a></h4>
+<h4><a class="toc-backref" href="#id263">Different runner scripts</a></h4>
<p>Test execution is normally started with the <span
class="prog">pybot</span> or
<span class="prog">jybot</span> commands. These commands are otherwise
identical, but
the former executes tests using the Python interpreter and the latter uses
@@ -6254,7 +6319,7 @@
outputs in some way.</p>
</div>
<div class="section" id="specifying-the-test-data-to-be-executed">
-<h4><a class="toc-backref" href="#id262">Specifying the test data to
be executed</a></h4>
+<h4><a class="toc-backref" href="#id264">Specifying the test data to
be executed</a></h4>
<p>Robot Framework test cases are created in <a class="reference
internal" href="#test-case-files">files</a> and <a class="reference
internal" href="#test-suite-directories">directories</a>,
and they are executed by giving the path to the file or directory in
question to the selected runner script. The path can be absolute or,
@@ -6289,7 +6354,7 @@
</pre>
</div>
<div class="section" id="using-command-line-options">
-<h4><a class="toc-backref" href="#id263">Using command line options</a></h4>
+<h4><a class="toc-backref" href="#id265">Using command line options</a></h4>
<p>Robot Framework provides a number of command line options that can be
used to control how test cases are executed and what outputs are
generated. The syntax for using them is explained in this
@@ -6335,7 +6400,7 @@
</div>
</div>
<div class="section" id="generated-outputs">
-<h4><a class="toc-backref" href="#id264">Generated outputs</a></h4>
+<h4><a class="toc-backref" href="#id266">Generated outputs</a></h4>
<p>The most visible output from test execution is the output displayed in
the command line. All executed test suites and test cases, as well as
their statuses, are shown there in real time. The example below shows the
@@ -6366,7 +6431,7 @@
discussed in more detail in the section <a class="reference internal"
href="#different-output-files">Different output files</a>.</p>
</div>
<div class="section" id="return-codes">
-<h4><a class="toc-backref" href="#id265">Return codes</a></h4>
+<h4><a class="toc-backref" href="#id267">Return codes</a></h4>
<p>Runner scripts communicate the overall test execution status to the
system running them using return codes. The basic rule is that the
return code is zero, which is a typical return code for success, when
@@ -6413,7 +6478,7 @@
</div>
</div>
<div class="section" id="post-processing-outputs">
-<h3><a class="toc-backref"
href="#id266">3.1.2   Post-processing outputs</a></h3>
+<h3><a class="toc-backref"
href="#id268">3.1.2   Post-processing outputs</a></h3>
<p><a class="reference internal" href="#output-file">XML output
files</a> that are generated during the test execution can be
post-processed afterwards by the <span class="prog">rebot</span> tool,
which is an integral
part of Robot Framework. It is used automatically when test
@@ -6425,7 +6490,7 @@
that arguments to <span class="prog">rebot</span> are XML output files
instead of test
data files or directories.</p>
<div class="section" id="creating-different-reports-and-logs">
-<h4><a class="toc-backref" href="#id267">Creating different reports
and logs</a></h4>
+<h4><a class="toc-backref" href="#id269">Creating different reports
and logs</a></h4>
<p>You can use <span class="prog">rebot</span> for creating the same
reports and logs that
are created automatically during the test execution. Of course, it is
not sensible to create the exactly same files, but, for example,
@@ -6444,7 +6509,7 @@
</pre>
</div>
<div class="section" id="combining-outputs">
-<h4><a class="toc-backref" href="#id268">Combining outputs</a></h4>
+<h4><a class="toc-backref" href="#id270">Combining outputs</a></h4>
<p>The most important feature of <span class="prog">rebot</span> is
its ability to combine
outputs from different test execution rounds. This capability allows,
for example, running the same test cases on different environments and
@@ -6470,7 +6535,7 @@
</div>
</div>
<div class="section" id="getting-help-on-the-command-line">
-<h3><a class="toc-backref"
href="#id269">3.1.3   Getting help on the command line</a></h3>
+<h3><a class="toc-backref"
href="#id271">3.1.3   Getting help on the command line</a></h3>
<p>Both when executing test cases with <span class="prog">pybot</span>
or <span class="prog">jybot</span> and
when post-processing reports with <span class="prog">rebot</span>, it
is possible to get
command line help with the option <span class="opt">--help</span> and
its short version
@@ -6491,7 +6556,7 @@
</pre>
</div>
<div class="section" id="handling-complicated-characters">
-<h3><a class="toc-backref"
href="#id270">3.1.4   Handling complicated characters</a></h3>
+<h3><a class="toc-backref"
href="#id272">3.1.4   Handling complicated characters</a></h3>
<p>Because spaces are used for separating options from each other, it is
problematic to use them in option values. Some options, such as
<span class="opt">--name</span>, automatically convert underscores to
spaces, but
@@ -6505,7 +6570,7 @@
post-processing outputs, and also some of the external supporting
tools have the same or similar capabilities.</p>
<div class="section" id="escaping-options">
-<h4><a class="toc-backref" href="#id271">Escaping options</a></h4>
+<h4><a class="toc-backref" href="#id273">Escaping options</a></h4>
<p>In Robot Framework's command line escaping mechanism,
problematic characters are escaped with freely selected text. The
command line option to use is <span class="opt">--escape</span> (short version
@@ -6609,7 +6674,7 @@
selected carefully.</p>
</div>
<div class="section" id="using-argument-files">
-<h4><a class="toc-backref" href="#id272">Using argument files</a></h4>
+<h4><a class="toc-backref" href="#id274">Using argument files</a></h4>
<p>Another possibility to handle complicated arguments is placing them
into a argument file and using <span class="opt">--argumentfile</span> (short
option <span class="opt">-A</span>) to specify the path to it, along
with possible other
@@ -6639,7 +6704,7 @@
</div>
</div>
<div class="section" id="creating-start-up-scripts">
-<h3><a class="toc-backref"
href="#id273">3.1.5   Creating start-up scripts</a></h3>
+<h3><a class="toc-backref"
href="#id275">3.1.5   Creating start-up scripts</a></h3>
<p>Test cases are often executed automatically by a continuous
integration system or some other mechanism. In such cases, there is a
need to have a script for starting the test execution, and possibly
@@ -6715,46 +6780,46 @@
</div>
</div>
<div class="section" id="configuring-execution">
-<h2><a class="toc-backref"
href="#id258">3.2   Configuring execution</a></h2>
+<h2><a class="toc-backref"
href="#id260">3.2   Configuring execution</a></h2>
<p>This section explains different command line options that can be used
for configuring the <a class="reference internal"
href="#starting-test-execution">test execution</a> or <a
class="reference internal" href="#post-processing-outputs">post-processing
outputs</a>. Options related to generated output files are discussed in
the <a class="reference internal" href="#created-outputs">next section</a>.</p>
-<div class="contents local topic" id="id56">
+<div class="contents local topic" id="id57">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#selecting-test-cases"
id="id274">3.2.1   Selecting test cases</a><ul>
-<li><a class="reference internal"
href="#by-test-suite-and-test-case-names" id="id275">By test suite and
test case names</a></li>
-<li><a class="reference internal" href="#by-tag-names" id="id276">By
tag names</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#setting-criticality"
id="id277">3.2.2   Setting criticality</a></li>
-<li><a class="reference internal" href="#setting-metadata"
id="id278">3.2.3   Setting metadata</a><ul>
-<li><a class="reference internal" href="#setting-the-name"
id="id279">Setting the name</a></li>
-<li><a class="reference internal" href="#setting-the-documentation"
id="id280">Setting the documentation</a></li>
-<li><a class="reference internal" href="#setting-free-metadata"
id="id281">Setting free metadata</a></li>
-<li><a class="reference internal" href="#setting-tags"
id="id282">Setting tags</a></li>
-</ul>
-</li>
-<li><a class="reference internal"
href="#adjusting-library-search-path"
id="id283">3.2.4   Adjusting library search path</a><ul>
-<li><a class="reference internal"
href="#locations-automatically-in-pythonpath" id="id284">Locations
automatically in PYTHONPATH</a></li>
-<li><a class="reference internal" href="#setting-pythonpath-in-system"
id="id285">Setting PYTHONPATH in system</a></li>
-<li><a class="reference internal"
href="#setting-classpath-in-the-system" id="id286">Setting CLASSPATH in
the system</a></li>
-<li><a class="reference internal" href="#using-the-pythonpath-option"
id="id287">Using the --pythonpath option</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#setting-variables"
id="id288">3.2.5   Setting variables</a></li>
-<li><a class="reference internal" href="#setting-the-execution-mode"
id="id289">3.2.6   Setting the execution mode</a></li>
-<li><a class="reference internal"
href="#controlling-the-monitor-output"
id="id290">3.2.7   Controlling the monitor output</a></li>
-<li><a class="reference internal" href="#setting-listeners"
id="id291">3.2.8   Setting listeners</a></li>
+<li><a class="reference internal" href="#selecting-test-cases"
id="id276">3.2.1   Selecting test cases</a><ul>
+<li><a class="reference internal"
href="#by-test-suite-and-test-case-names" id="id277">By test suite and
test case names</a></li>
+<li><a class="reference internal" href="#by-tag-names" id="id278">By
tag names</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#setting-criticality"
id="id279">3.2.2   Setting criticality</a></li>
+<li><a class="reference internal" href="#setting-metadata"
id="id280">3.2.3   Setting metadata</a><ul>
+<li><a class="reference internal" href="#setting-the-name"
id="id281">Setting the name</a></li>
+<li><a class="reference internal" href="#setting-the-documentation"
id="id282">Setting the documentation</a></li>
+<li><a class="reference internal" href="#setting-free-metadata"
id="id283">Setting free metadata</a></li>
+<li><a class="reference internal" href="#setting-tags"
id="id284">Setting tags</a></li>
+</ul>
+</li>
+<li><a class="reference internal"
href="#adjusting-library-search-path"
id="id285">3.2.4   Adjusting library search path</a><ul>
+<li><a class="reference internal"
href="#locations-automatically-in-pythonpath" id="id286">Locations
automatically in PYTHONPATH</a></li>
+<li><a class="reference internal" href="#setting-pythonpath-in-system"
id="id287">Setting PYTHONPATH in system</a></li>
+<li><a class="reference internal"
href="#setting-classpath-in-the-system" id="id288">Setting CLASSPATH in
the system</a></li>
+<li><a class="reference internal" href="#using-the-pythonpath-option"
id="id289">Using the --pythonpath option</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#setting-variables"
id="id290">3.2.5   Setting variables</a></li>
+<li><a class="reference internal" href="#setting-the-execution-mode"
id="id291">3.2.6   Setting the execution mode</a></li>
+<li><a class="reference internal"
href="#controlling-the-monitor-output"
id="id292">3.2.7   Controlling the monitor output</a></li>
+<li><a class="reference internal" href="#setting-listeners"
id="id293">3.2.8   Setting listeners</a></li>
</ul>
</div>
<div class="section" id="selecting-test-cases">
-<h3><a class="toc-backref"
href="#id274">3.2.1   Selecting test cases</a></h3>
+<h3><a class="toc-backref"
href="#id276">3.2.1   Selecting test cases</a></h3>
<p>Robot Framework offers several command line options for selecting
which test cases to execute. The same options also work when
post-processing outputs with the <span class="prog">rebot</span> tool.</p>
<div class="section" id="by-test-suite-and-test-case-names">
-<h4><a class="toc-backref" href="#id275">By test suite and test case names</a></h4>
+<h4><a class="toc-backref" href="#id277">By test suite and test case names</a></h4>
<p>Test suites and test cases can be selected by their names with the command
line options <span class="opt">--suite (-s)</span> and <span
class="opt">--test (-t)</span>,
respectively. Both of these options can be used several times to
@@ -6787,7 +6852,7 @@
flexible.</p>
</div>
<div class="section" id="by-tag-names">
-<h4><a class="toc-backref" href="#id276">By tag names</a></h4>
+<h4><a class="toc-backref" href="#id278">By tag names</a></h4>
<p>It is possible to include and exclude test cases by <a
class="reference internal" href="#tagging-test-cases">tag</a> names
with the
<span class="opt">--include (-i)</span> and <span
class="opt">--exclude (-e)</span> options,
respectively. When the former is used, only test cases having a
@@ -6833,7 +6898,7 @@
</div>
</div>
<div class="section" id="setting-criticality">
-<h3><a class="toc-backref"
href="#id277">3.2.2   Setting criticality</a></h3>
+<h3><a class="toc-backref"
href="#id279">3.2.2   Setting criticality</a></h3>
<p>The final result of test execution is determined on the basis of
critical tests. If a single critical test fails, the whole test run is
considered failed. On the other hand, non-critical test cases can
@@ -6871,9 +6936,9 @@
</div>
</div>
<div class="section" id="setting-metadata">
-<h3><a class="toc-backref"
href="#id278">3.2.3   Setting metadata</a></h3>
+<h3><a class="toc-backref"
href="#id280">3.2.3   Setting metadata</a></h3>
<div class="section" id="setting-the-name">
-<h4><a class="toc-backref" href="#id279">Setting the name</a></h4>
+<h4><a class="toc-backref" href="#id281">Setting the name</a></h4>
<p>When Robot Framework parses test data, <a class="reference
internal" href="#test-suite-name-and-documentation">test suite names
are created
from file and directory names</a>. The name of the top-level test suite
can, however, be overridden with the command line option
@@ -6881,14 +6946,14 @@
spaces automatically, and words in the name capitalized.</p>
</div>
<div class="section" id="setting-the-documentation">
-<h4><a class="toc-backref" href="#id280">Setting the documentation</a></h4>
+<h4><a class="toc-backref" href="#id282">Setting the documentation</a></h4>
<p>In addition to <a class="reference internal"
href="#test-suite-name-and-documentation">defining documentation in the
test data</a>, documentation
of the top-level suite can be given from the command line with the
option <span class="opt">--doc (-D)</span>. Underscores in the given documentation
are converted to spaces, and it may contain simple <a class="reference
internal" href="#documentation-formatting">HTML formatting</a>.</p>
</div>
<div class="section" id="setting-free-metadata">
-<h4><a class="toc-backref" href="#id281">Setting free metadata</a></h4>
+<h4><a class="toc-backref" href="#id283">Setting free metadata</a></h4>
<p><a class="reference internal" href="#free-test-suite-metadata">Free
test suite metadata</a> may also be given from the command line
with the option <span class="opt">--metadata (-M)</span>. The argument
must be in
the format <span class="opt">name:value</span>, where <span
class="opt">name</span> the name of
@@ -6898,14 +6963,14 @@
several times to set multiple metadata.</p>
</div>
<div class="section" id="setting-tags">
-<h4><a class="toc-backref" href="#id282">Setting tags</a></h4>
+<h4><a class="toc-backref" href="#id284">Setting tags</a></h4>
<p>The command line option <span class="opt">--settag (-G)</span> can
be used to set
the given tag to all executed test cases. This option may be used
several times to set multiple tags.</p>
</div>
</div>
<div class="section" id="adjusting-library-search-path">
-<h3><a class="toc-backref"
href="#id283">3.2.4   Adjusting library search path</a></h3>
+<h3><a class="toc-backref"
href="#id285">3.2.4   Adjusting library search path</a></h3>
<p>When a <a class="reference internal"
href="#taking-test-libraries-into-use">test library is taken into
use</a>, Robot Framework uses the Python
or Jython interpreter to import a module implementing the library from
the system. The location where these modules are searched from is called
@@ -6918,7 +6983,7 @@
PYTHONPATH and CLASSPATH, but regardless of the selected approach, it is
recommended to use a <a class="reference internal"
href="#creating-start-up-scripts">custom start-up script</a>.</p>
<div class="section" id="locations-automatically-in-pythonpath">
-<h4><a class="toc-backref" href="#id284">Locations automatically in PYTHONPATH</a></h4>
+<h4><a class="toc-backref" href="#id286">Locations automatically in PYTHONPATH</a></h4>
<p>Python and Jython installations put their own library directories into
PYTHONPATH automatically. This means that test libraries <a
class="reference internal" href="#packaging-libraries">packaged
using Python's own packaging system</a> are automatically installed
@@ -6927,7 +6992,7 @@
directory where tests are executed from into PYTHONPATH.</p>
</div>
<div class="section" id="setting-pythonpath-in-system">
-<h4><a class="toc-backref" href="#id285">Setting PYTHONPATH in system</a></h4>
+<h4><a class="toc-backref" href="#id287">Setting PYTHONPATH in system</a></h4>
<p>There are several ways to alter PYTHONPATH in the system, but the most
common one is setting an environment variable with the same name
before the test execution. Jython actually does not use PYTHONPATH
@@ -6936,7 +7001,7 @@
regardless the interpreter.</p>
</div>
<div class="section" id="setting-classpath-in-the-system">
-<h4><a class="toc-backref" href="#id286">Setting CLASSPATH in the system</a></h4>
+<h4><a class="toc-backref" href="#id288">Setting CLASSPATH in the system</a></h4>
<p>CLASSPATH is used only with Jython, and the most common way to alter
it is setting an environment variable similarly as with PYTHONPATH.
Note that instead of CLASSPATH, it is always possible to use
@@ -6944,7 +7009,7 @@
with Java.</p>
</div>
<div class="section" id="using-the-pythonpath-option">
-<h4><a class="toc-backref" href="#id287">Using the --pythonpath option</a></h4>
+<h4><a class="toc-backref" href="#id289">Using the --pythonpath option</a></h4>
<p>Robot Framework also has a separate command line option
<span class="opt">--pythonpath (-P)</span> for adding directories or
archives into
PYTHONPATH. Multiple paths can be given by separating them with a
@@ -6960,7 +7025,7 @@
</div>
</div>
<div class="section" id="setting-variables">
-<h3><a class="toc-backref"
href="#id288">3.2.5   Setting variables</a></h3>
+<h3><a class="toc-backref"
href="#id290">3.2.5   Setting variables</a></h3>
<p><a class="reference internal" href="#variables">Variables</a> can
be set from the command line either <a class="reference internal" href="#setting-variables-in-command-line">individually</a>
using the <span class="opt">--variable (-v)</span> option or through
<a class="reference internal" href="#variable-files">variable files</a>
with the <span class="opt">--variablefile (-V)</span> option.
Variables and variable
@@ -6974,7 +7039,7 @@
</pre>
</div>
<div class="section" id="setting-the-execution-mode">
-<h3><a class="toc-backref"
href="#id289">3.2.6   Setting the execution mode</a></h3>
+<h3><a class="toc-backref"
href="#id291">3.2.6   Setting the execution mode</a></h3>
<p>The command line option <span class="opt">--runmode</span> can be
used to alter the test
execution. Possible values for it are listed and explained below,
other values are silently ignored. All these values are case-insensitive.</p>
@@ -6996,7 +7061,7 @@
</dl>
</div>
<div class="section" id="controlling-the-monitor-output">
-<h3><a class="toc-backref"
href="#id290">3.2.7   Controlling the monitor output</a></h3>
+<h3><a class="toc-backref"
href="#id292">3.2.7   Controlling the monitor output</a></h3>
<p>The width of the test execution output in the console is set using the
option <span class="opt">--monitorwidth (-W)</span>. The default value
for the monitor
width is 78 characters.</p>
@@ -7021,7 +7086,7 @@
</pre>
</div>
<div class="section" id="setting-listeners">
-<h3><a class="toc-backref"
href="#id291">3.2.8   Setting listeners</a></h3>
+<h3><a class="toc-backref"
href="#id293">3.2.8   Setting listeners</a></h3>
<p>So-called <a class="reference internal"
href="#using-listener-interface">listeners</a> can be used for
monitoring the test
execution. They are taken into use with the command line option
<span class="opt">--listener</span>, and the specified listeners must
be in the <a class="reference internal" href="#adjusting-library-search-path">module
@@ -7029,53 +7094,53 @@
</div>
</div>
<div class="section" id="created-outputs">
-<h2><a class="toc-backref" href="#id259">3.3   Created outputs</a></h2>
+<h2><a class="toc-backref" href="#id261">3.3   Created outputs</a></h2>
<p>Several output files are created when tests are executed, and most of
them are somehow related to test results. This section discusses what
outputs are created, how to configure where they are created, and how
to fine-tune their contents.</p>
-<div class="contents local topic" id="id66">
+<div class="contents local topic" id="id67">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#different-output-files"
id="id292">3.3.1   Different output files</a><ul>
-<li><a class="reference internal" href="#output-directory"
id="id293">Output directory</a></li>
-<li><a class="reference internal" href="#output-file"
id="id294">Output file</a></li>
-<li><a class="reference internal" href="#log-file" id="id295">Log file</a></li>
-<li><a class="reference internal" href="#report-file"
id="id296">Report file</a></li>
-<li><a class="reference internal" href="#summary-file"
id="id297">Summary file</a></li>
-<li><a class="reference internal" href="#debug-file" id="id298">Debug file</a></li>
-<li><a class="reference internal" href="#timestamping-output-files"
id="id299">Timestamping output files</a></li>
-<li><a class="reference internal" href="#setting-titles"
id="id300">Setting titles</a></li>
+<li><a class="reference internal" href="#different-output-files"
id="id294">3.3.1   Different output files</a><ul>
+<li><a class="reference internal" href="#output-directory"
id="id295">Output directory</a></li>
+<li><a class="reference internal" href="#output-file"
id="id296">Output file</a></li>
+<li><a class="reference internal" href="#log-file" id="id297">Log file</a></li>
+<li><a class="reference internal" href="#report-file"
id="id298">Report file</a></li>
+<li><a class="reference internal" href="#summary-file"
id="id299">Summary file</a></li>
+<li><a class="reference internal" href="#debug-file" id="id300">Debug file</a></li>
+<li><a class="reference internal" href="#timestamping-output-files"
id="id301">Timestamping output files</a></li>
+<li><a class="reference internal" href="#setting-titles"
id="id302">Setting titles</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#log-levels"
id="id301">3.3.2   Log levels</a><ul>
-<li><a class="reference internal" href="#available-log-levels"
id="id302">Available log levels</a></li>
-<li><a class="reference internal" href="#setting-log-level"
id="id303">Setting log level</a></li>
+<li><a class="reference internal" href="#log-levels"
id="id303">3.3.2   Log levels</a><ul>
+<li><a class="reference internal" href="#available-log-levels"
id="id304">Available log levels</a></li>
+<li><a class="reference internal" href="#setting-log-level"
id="id305">Setting log level</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#splitting-outputs"
id="id304">3.3.3   Splitting outputs</a><ul>
-<li><a class="reference internal" href="#benefits" id="id305">Benefits</a></li>
-<li><a class="reference internal" href="#specifying-a-split-level"
id="id306">Specifying a split level</a></li>
-<li><a class="reference internal" href="#examples" id="id307">Examples</a></li>
+<li><a class="reference internal" href="#splitting-outputs"
id="id306">3.3.3   Splitting outputs</a><ul>
+<li><a class="reference internal" href="#benefits" id="id307">Benefits</a></li>
+<li><a class="reference internal" href="#specifying-a-split-level"
id="id308">Specifying a split level</a></li>
+<li><a class="reference internal" href="#examples" id="id309">Examples</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#configuring-statistics"
id="id308">3.3.4   Configuring statistics</a><ul>
-<li><a class="reference internal"
href="#configuring-displayed-suite-statistics" id="id309">Configuring
displayed suite statistics</a></li>
-<li><a class="reference internal"
href="#including-and-excluding-tag-statistics" id="id310">Including and
excluding tag statistics</a></li>
-<li><a class="reference internal"
href="#generating-combined-tag-statistics" id="id311">Generating
combined tag statistics</a></li>
-<li><a class="reference internal"
href="#creating-links-from-tag-names" id="id312">Creating links from
tag names</a></li>
-<li><a class="reference internal" href="#adding-documentation-to-tags"
id="id313">Adding documentation to tags</a></li>
+<li><a class="reference internal" href="#configuring-statistics"
id="id310">3.3.4   Configuring statistics</a><ul>
+<li><a class="reference internal"
href="#configuring-displayed-suite-statistics" id="id311">Configuring
displayed suite statistics</a></li>
+<li><a class="reference internal"
href="#including-and-excluding-tag-statistics" id="id312">Including and
excluding tag statistics</a></li>
+<li><a class="reference internal"
href="#generating-combined-tag-statistics" id="id313">Generating
combined tag statistics</a></li>
+<li><a class="reference internal"
href="#creating-links-from-tag-names" id="id314">Creating links from
tag names</a></li>
+<li><a class="reference internal" href="#adding-documentation-to-tags"
id="id315">Adding documentation to tags</a></li>
</ul>
</li>
-<li><a class="reference internal"
href="#additional-options-for-post-processing-outputs"
id="id314">3.3.5   Additional options for
post-processing outputs</a><ul>
-<li><a class="reference internal"
href="#setting-times-for-combined-outputs" id="id315">Setting times for
combined outputs</a></li>
-<li><a class="reference internal"
href="#removing-keywords-from-outputs" id="id316">Removing keywords
from outputs</a></li>
+<li><a class="reference internal"
href="#additional-options-for-post-processing-outputs"
id="id316">3.3.5   Additional options for
post-processing outputs</a><ul>
+<li><a class="reference internal"
href="#setting-times-for-combined-outputs" id="id317">Setting times for
combined outputs</a></li>
+<li><a class="reference internal"
href="#removing-keywords-from-outputs" id="id318">Removing keywords
from outputs</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#system-log"
id="id317">3.3.6   System log</a></li>
+<li><a class="reference internal" href="#system-log"
id="id319">3.3.6   System log</a></li>
</ul>
</div>
<div class="section" id="different-output-files">
-<h3><a class="toc-backref"
href="#id292">3.3.1   Different output files</a></h3>
+<h3><a class="toc-backref"
href="#id294">3.3.1   Different output files</a></h3>
<p>This section explains what different output files can be created and
how to configure where they are created. Output files are configured
using command line options, which get the path to the output file in
@@ -7083,7 +7148,7 @@
(case-insensitive) can be used to disable creating a certain output
file.</p>
<div class="section" id="output-directory">
-<h4><a class="toc-backref" href="#id293">Output directory</a></h4>
+<h4><a class="toc-backref" href="#id295">Output directory</a></h4>
<p>All output files can be set using an absolute path, in which case they
are created to the specified place, but in other cases, the path is
considered relative to the output directory. The default output
@@ -7095,7 +7160,7 @@
is created automatically, if it does not exist already.</p>
</div>
<div class="section" id="output-file">
-<h4><a class="toc-backref" href="#id294">Output file</a></h4>
+<h4><a class="toc-backref" href="#id296">Output file</a></h4>
<p>Output files contain all the test execution results in the XML
format. <a class="reference internal" href="#log-file">Log</a>, <a
class="reference internal" href="#report-file">report</a>, and <a
class="reference internal" href="#summary-file">summary</a> files are
generated based on
output files, and output files can also be <a class="reference
internal" href="#post-processing-outputs">combined and otherwise
@@ -7107,7 +7172,7 @@
not created unless this option is explicitly used.</p>
</div>
<div class="section" id="log-file">
-<h4><a class="toc-backref" href="#id295">Log file</a></h4>
+<h4><a class="toc-backref" href="#id297">Log file</a></h4>
<p>Log files contain details about the executed test cases in HTML
format. They have a hierarchical structure showing test suite, test
case and keyword details. Log files are needed nearly every time when
@@ -7128,7 +7193,7 @@
</div>
</div>
<div class="section" id="report-file">
-<h4><a class="toc-backref" href="#id296">Report file</a></h4>
+<h4><a class="toc-backref" href="#id298">Report file</a></h4>
<p>Report files contain an overview of the test execution results in HTML
format. They have statistics based on tags and executed test suites,
as well as a list of all executed test cases. When both reports and
@@ -7151,7 +7216,7 @@
</div>
</div>
<div class="section" id="summary-file">
-<h4><a class="toc-backref" href="#id297">Summary file</a></h4>
+<h4><a class="toc-backref" href="#id299">Summary file</a></h4>
<p>Summary files contain the same statistics as reports, and their
background color is similarly green or red, depending on the overall
test execution status. However, they have no test case details, which
@@ -7166,7 +7231,7 @@
</div>
</div>
<div class="section" id="debug-file">
-<h4><a class="toc-backref" href="#id298">Debug file</a></h4>
+<h4><a class="toc-backref" href="#id300">Debug file</a></h4>
<p>Debug files are plain text files that are written during the test
execution. All messages got from test libraries are written to them,
as well as information about started and ended test suites, test cases
@@ -7178,7 +7243,7 @@
<span class="opt">--debugfile (-b)</span> is used explicitly.</p>
</div>
<div class="section" id="timestamping-output-files">
-<h4><a class="toc-backref" href="#id299">Timestamping output files</a></h4>
+<h4><a class="toc-backref" href="#id301">Timestamping output files</a></h4>
<p>All output files listed in this section can be automatically
timestamped with the option <span class="opt">--timestampoutputs
(-T)</span>, which
is one of the rare options taking no value. When this option is used, a
@@ -7192,7 +7257,7 @@
</pre>
</div>
<div class="section" id="setting-titles">
-<h4><a class="toc-backref" href="#id300">Setting titles</a></h4>
+<h4><a class="toc-backref" href="#id302">Setting titles</a></h4>
<p>The default titles for <a class="reference internal"
href="#log-file">log</a>, <a class="reference internal"
href="#report-file">report</a> and <a class="reference internal"
href="#summary-file">summary</a> files are generated
by prefixing the name of the top-level test suite with <span class="name">Test
Log</span>, <span class="name">Test Report</span> or <span
class="name">Summary Report</span>. Custom titles can
@@ -7208,9 +7273,9 @@
</div>
</div>
<div class="section" id="log-levels">
-<h3><a class="toc-backref" href="#id301">3.3.2   Log levels</a></h3>
+<h3><a class="toc-backref" href="#id303">3.3.2   Log levels</a></h3>
<div class="section" id="available-log-levels">
-<h4><a class="toc-backref" href="#id302">Available log levels</a></h4>
+<h4><a class="toc-backref" href="#id304">Available log levels</a></h4>
<p>Messages in <a class="reference internal" href="#log-file">log
files</a> can have different log levels. Some of the
messages are written by Robot Framework itself, but also executed
keywords can <a class="reference internal"
href="#logging-information">log information</a> using different levels.
The available
@@ -7233,7 +7298,7 @@
</dl>
</div>
<div class="section" id="setting-log-level">
-<h4><a class="toc-backref" href="#id303">Setting log level</a></h4>
+<h4><a class="toc-backref" href="#id305">Setting log level</a></h4>
<p>By default, log messages below <span class="msg">INFO</span> are
not logged, but this
threshold level can be changed from the command line using the
<span class="opt">--loglevel (-L)</span> option. This option takes any
of the
@@ -7248,9 +7313,9 @@
</div>
</div>
<div class="section" id="splitting-outputs">
-<h3><a class="toc-backref"
href="#id304">3.3.3   Splitting outputs</a></h3>
+<h3><a class="toc-backref"
href="#id306">3.3.3   Splitting outputs</a></h3>
<div class="section" id="benefits">
-<h4><a class="toc-backref" href="#id305">Benefits</a></h4>
+<h4><a class="toc-backref" href="#id307">Benefits</a></h4>
<p>When executing a large number of test cases, the size of log files can
increase to the extent that opening them into browsers is
slow. Additionally, since log files can be created only after output
@@ -7268,7 +7333,7 @@
<span class="var">${OUTPUT_FILE}</span> always contain the path to the
current file.</p>
</div>
<div class="section" id="specifying-a-split-level">
-<h4><a class="toc-backref" href="#id306">Specifying a split level</a></h4>
+<h4><a class="toc-backref" href="#id308">Specifying a split level</a></h4>
<p>Outputs are split from a certain test suite level. Suites below this
level will get their own outputs, and everything above the level will
be in an index file, which has links to lower-level files. Only
@@ -7282,7 +7347,7 @@
the basename and extension.</p>
</div>
<div class="section" id="examples">
-<h4><a class="toc-backref" href="#id307">Examples</a></h4>
+<h4><a class="toc-backref" href="#id309">Examples</a></h4>
<p>Explaining how splitting outputs actually works is easiest with
examples, and it is also a good idea to experiment with real test data.
In these examples we assume that test cases are organized into test
@@ -7451,14 +7516,14 @@
</div>
</div>
<div class="section" id="configuring-statistics">
-<h3><a class="toc-backref"
href="#id308">3.3.4   Configuring statistics</a></h3>
+<h3><a class="toc-backref"
href="#id310">3.3.4   Configuring statistics</a></h3>
<p>There are several command line options that can be used to configure
and adjust the contents of the <span class="name">Statistics by
Tag</span>, <span class="name">Statistics
by Suite</span> and <span class="name">Test Details by Tag</span>
tables in different output
files. All these options work both when executing test cases and when
post-processing outputs.</p>
<div class="section" id="configuring-displayed-suite-statistics">
-<h4><a class="toc-backref" href="#id309">Configuring displayed suite statistics</a></h4>
+<h4><a class="toc-backref" href="#id311">Configuring displayed suite statistics</a></h4>
<p>When a deeper suite structure is executed, showing all the test suite
levels in the <span class="name">Statistics by Suite</span> table may
make the table
somewhat difficult to read. You can control the number of levels
@@ -7467,7 +7532,7 @@
the whole table is removed.</p>
</div>
<div class="section" id="including-and-excluding-tag-statistics">
-<h4><a class="toc-backref" href="#id310">Including and excluding tag statistics</a></h4>
+<h4><a class="toc-backref" href="#id312">Including and excluding tag statistics</a></h4>
<p>When many tags are used, the <span class="name">Statistics by
Tag</span> table can become
quite congested. If this happens, the command line options
<span class="opt">--tagstatinclude</span> and <span
class="opt">--tagstatexclude</span> can be
@@ -7485,7 +7550,7 @@
interesting can be recommended.</p>
</div>
<div class="section" id="generating-combined-tag-statistics">
-<h4><a class="toc-backref" href="#id311">Generating combined tag statistics</a></h4>
+<h4><a class="toc-backref" href="#id313">Generating combined tag statistics</a></h4>
<p>The command line option <span class="opt">--tagstatcombine</span>
can be used to
generate aggregate tags that combine statistics from multiple
tags. These new combined tags are shown in the <span
class="name">Statistics by
@@ -7516,7 +7581,7 @@
</div>
</div>
<div class="section" id="creating-links-from-tag-names">
-<h4><a class="toc-backref" href="#id312">Creating links from tag names</a></h4>
+<h4><a class="toc-backref" href="#id314">Creating links from tag names</a></h4>
<p>You can add external links to the <span class="name">Statistics by
Tag</span> table by
using the command line option <span class="opt">--tagstatlink</span>.
Arguments to this
option are given in the format <span class="opt">tag:link:name</span>,
where <span class="opt">tag</span>
@@ -7541,7 +7606,7 @@
</div>
</div>
<div class="section" id="adding-documentation-to-tags">
-<h4><a class="toc-backref" href="#id313">Adding documentation to tags</a></h4>
+<h4><a class="toc-backref" href="#id315">Adding documentation to tags</a></h4>
<p>Tags can be given a documentation with the command line option
<span class="opt">--tagdoc</span>, which takes an argument in the format
<span class="opt">tag:doc</span>. "tag" is the name of the
tag to assign
@@ -7560,11 +7625,11 @@
</div>
</div>
<div class="section" id="additional-options-for-post-processing-outputs">
-<h3><a class="toc-backref"
href="#id314">3.3.5   Additional options for
post-processing outputs</a></h3>
+<h3><a class="toc-backref"
href="#id316">3.3.5   Additional options for
post-processing outputs</a></h3>
<p>These options are available only when <a class="reference internal"
href="#post-processing-outputs">post-processing outputs</a> with
<span class="prog">rebot</span>.</p>
<div class="section" id="setting-times-for-combined-outputs">
-<h4><a class="toc-backref" href="#id315">Setting times for combined outputs</a></h4>
+<h4><a class="toc-backref" href="#id317">Setting times for combined outputs</a></h4>
<p>When <a class="reference internal"
href="#combining-outputs">combining outputs</a>, it is possible to set
the start and end
time of the combined test suite using the options
<span class="opt">--starttime</span> and <span
class="opt">--endtime</span>, respectively. This is
@@ -7584,7 +7649,7 @@
</pre>
</div>
<div class="section" id="removing-keywords-from-outputs">
-<h4><a class="toc-backref" href="#id316">Removing keywords from outputs</a></h4>
+<h4><a class="toc-backref" href="#id318">Removing keywords from outputs</a></h4>
<p>Most of the content of <a class="reference internal"
href="#output-file">output files</a> comes from keywords and
especially their log messages. When creating higher level reports, log
files are not necessarily needed at all, and then keywords and their
@@ -7607,7 +7672,7 @@
</div>
</div>
<div class="section" id="system-log">
-<h3><a class="toc-backref" href="#id317">3.3.6   System log</a></h3>
+<h3><a class="toc-backref" href="#id319">3.3.6   System log</a></h3>
<p>Robot Framework has its own plain-text system log where it writes
information about</p>
<blockquote>
@@ -7638,73 +7703,73 @@
</div>
</div>
<div class="section" id="extending-robot-framework">
-<h1><a class="toc-backref" href="#id136">4   Extending
Robot Framework</a></h1>
-<div class="contents local topic" id="id71">
+<h1><a class="toc-backref" href="#id137">4   Extending
Robot Framework</a></h1>
+<div class="contents local topic" id="id72">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#creating-test-libraries"
id="id318">4.1   Creating test libraries</a></li>
-<li><a class="reference internal" href="#using-listener-interface"
id="id319">4.2   Using listener interface</a></li>
-<li><a class="reference internal" href="#using-internal-apis"
id="id320">4.3   Using internal APIs</a></li>
+<li><a class="reference internal" href="#creating-test-libraries"
id="id320">4.1   Creating test libraries</a></li>
+<li><a class="reference internal" href="#using-listener-interface"
id="id321">4.2   Using listener interface</a></li>
+<li><a class="reference internal" href="#using-internal-apis"
id="id322">4.3   Using internal APIs</a></li>
</ul>
</div>
<div class="section" id="creating-test-libraries">
-<h2><a class="toc-backref" href="#id318">4.1   Creating
test libraries</a></h2>
+<h2><a class="toc-backref" href="#id320">4.1   Creating
test libraries</a></h2>
<p>Robot Framework's actual testing capabilities are provided by test
libraries. There are many existing libraries, some of which are even
bundled with the core framework, but there is still often a need to
create new ones. This task is not too complicated because, as this
chapter illustrates, Robot Framework's library API is simple
and straightforward.</p>
-<div class="contents local topic" id="id72">
+<div class="contents local topic" id="id73">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#id73" id="id321">4.1.1   Introduction</a><ul>
-<li><a class="reference internal"
href="#supported-programming-languages" id="id322">Supported
programming languages</a></li>
-<li><a class="reference internal" href="#different-test-library-apis"
id="id323">Different test library APIs</a></li>
+<li><a class="reference internal" href="#id74" id="id323">4.1.1   Introduction</a><ul>
+<li><a class="reference internal"
href="#supported-programming-languages" id="id324">Supported
programming languages</a></li>
+<li><a class="reference internal" href="#different-test-library-apis"
id="id325">Different test library APIs</a></li>
</ul>
</li>
-<li><a class="reference internal"
href="#creating-test-library-class-or-module"
id="id324">4.1.2   Creating test library class or module</a><ul>
-<li><a class="reference internal" href="#test-library-names"
id="id325">Test library names</a></li>
-<li><a class="reference internal"
href="#providing-arguments-to-test-libraries" id="id326">Providing
arguments to test libraries</a></li>
-<li><a class="reference internal" href="#test-library-scope"
id="id327">Test library scope</a></li>
+<li><a class="reference internal"
href="#creating-test-library-class-or-module"
id="id326">4.1.2   Creating test library class or module</a><ul>
+<li><a class="reference internal" href="#test-library-names"
id="id327">Test library names</a></li>
+<li><a class="reference internal"
href="#providing-arguments-to-test-libraries" id="id328">Providing
arguments to test libraries</a></li>
+<li><a class="reference internal" href="#test-library-scope"
id="id329">Test library scope</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#creating-static-keywords"
id="id328">4.1.3   Creating static keywords</a><ul>
-<li><a class="reference internal" href="#keyword-names"
id="id329">Keyword names</a></li>
-<li><a class="reference internal" href="#keyword-arguments"
id="id330">Keyword arguments</a></li>
+<li><a class="reference internal" href="#creating-static-keywords"
id="id330">4.1.3   Creating static keywords</a><ul>
+<li><a class="reference internal" href="#keyword-names"
id="id331">Keyword names</a></li>
+<li><a class="reference internal" href="#keyword-arguments"
id="id332">Keyword arguments</a></li>
</ul>
</li>
-<li><a class="reference internal"
href="#communicating-with-robot-framework"
id="id331">4.1.4   Communicating with Robot Framework</a><ul>
-<li><a class="reference internal" href="#reporting-keyword-status"
id="id332">Reporting keyword status</a></li>
-<li><a class="reference internal" href="#logging-information"
id="id333">Logging information</a></li>
-<li><a class="reference internal" href="#returning-values"
id="id334">Returning values</a></li>
+<li><a class="reference internal"
href="#communicating-with-robot-framework"
id="id333">4.1.4   Communicating with Robot Framework</a><ul>
+<li><a class="reference internal" href="#reporting-keyword-status"
id="id334">Reporting keyword status</a></li>
+<li><a class="reference internal" href="#logging-information"
id="id335">Logging information</a></li>
+<li><a class="reference internal" href="#returning-values"
id="id336">Returning values</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#distributing-test-libraries"
id="id335">4.1.5   Distributing test libraries</a><ul>
-<li><a class="reference internal" href="#documenting-libraries"
id="id336">Documenting libraries</a></li>
-<li><a class="reference internal" href="#testing-libraries"
id="id337">Testing libraries</a></li>
-<li><a class="reference internal" href="#packaging-libraries"
id="id338">Packaging libraries</a></li>
+<li><a class="reference internal" href="#distributing-test-libraries"
id="id337">4.1.5   Distributing test libraries</a><ul>
+<li><a class="reference internal" href="#documenting-libraries"
id="id338">Documenting libraries</a></li>
+<li><a class="reference internal" href="#testing-libraries"
id="id339">Testing libraries</a></li>
+<li><a class="reference internal" href="#packaging-libraries"
id="id340">Packaging libraries</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#dynamic-library-api"
id="id339">4.1.6   Dynamic library API</a><ul>
-<li><a class="reference internal" href="#getting-keyword-names"
id="id340">Getting keyword names</a></li>
-<li><a class="reference internal" href="#running-keywords"
id="id341">Running keywords</a></li>
-<li><a class="reference internal" href="#getting-keyword-arguments"
id="id342">Getting keyword arguments</a></li>
-<li><a class="reference internal"
href="#getting-keyword-documentation" id="id343">Getting keyword documentation</a></li>
-<li><a class="reference internal" href="#summary" id="id344">Summary</a></li>
+<li><a class="reference internal" href="#dynamic-library-api"
id="id341">4.1.6   Dynamic library API</a><ul>
+<li><a class="reference internal" href="#getting-keyword-names"
id="id342">Getting keyword names</a></li>
+<li><a class="reference internal" href="#running-keywords"
id="id343">Running keywords</a></li>
+<li><a class="reference internal" href="#getting-keyword-arguments"
id="id344">Getting keyword arguments</a></li>
+<li><a class="reference internal"
href="#getting-keyword-documentation" id="id345">Getting keyword documentation</a></li>
+<li><a class="reference internal" href="#summary" id="id346">Summary</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#hybrid-library-api"
id="id345">4.1.7   Hybrid library API</a><ul>
-<li><a class="reference internal" href="#id84" id="id346">Getting
keyword names</a></li>
-<li><a class="reference internal" href="#id85" id="id347">Running keywords</a></li>
-<li><a class="reference internal"
href="#getting-keyword-arguments-and-documentation" id="id348">Getting
keyword arguments and documentation</a></li>
-<li><a class="reference internal" href="#id87" id="id349">Summary</a></li>
+<li><a class="reference internal" href="#hybrid-library-api"
id="id347">4.1.7   Hybrid library API</a><ul>
+<li><a class="reference internal" href="#id85" id="id348">Getting
keyword names</a></li>
+<li><a class="reference internal" href="#id86" id="id349">Running keywords</a></li>
+<li><a class="reference internal"
href="#getting-keyword-arguments-and-documentation" id="id350">Getting
keyword arguments and documentation</a></li>
+<li><a class="reference internal" href="#id88" id="id351">Summary</a></li>
</ul>
</li>
</ul>
</div>
-<div class="section" id="id73">
-<h3><a class="toc-backref" href="#id321">4.1.1   Introduction</a></h3>
+<div class="section" id="id74">
+<h3><a class="toc-backref" href="#id323">4.1.1   Introduction</a></h3>
<div class="section" id="supported-programming-languages">
-<h4><a class="toc-backref" href="#id322">Supported programming languages</a></h4>
+<h4><a class="toc-backref" href="#id324">Supported programming languages</a></h4>
<p>Robot Framework itself is written with <a class="reference
external" href="http://www.python.org/">Python</a>, so naturally, test
libraries extending it can be implemented using the same
language. Additionally, it is possible to write libraries using <a
class="reference external" href="http://java.sun.com/">Java</a>,
@@ -7725,7 +7790,7 @@
Framework in the future.</p>
</div>
<div class="section" id="different-test-library-apis">
-<h4><a class="toc-backref" href="#id323">Different test library APIs</a></h4>
+<h4><a class="toc-backref" href="#id325">Different test library APIs</a></h4>
<p>Robot Framework has three different test library APIs.</p>
<p>Static API</p>
<blockquote>
@@ -7761,13 +7826,13 @@
</div>
</div>
<div class="section" id="creating-test-library-class-or-module">
-<h3><a class="toc-backref"
href="#id324">4.1.2   Creating test library class or module</a></h3>
+<h3><a class="toc-backref"
href="#id326">4.1.2   Creating test library class or module</a></h3>
<p>Test libraries can be implemented as Python modules or Python
or Java classes. Using modules is possible only with the static API,
and more complicated libraries are normally better implemented as classes
even then.</p>
<div class="section" id="test-library-names">
-<h4><a class="toc-backref" href="#id325">Test library names</a></h4>
+<h4><a class="toc-backref" href="#id327">Test library names</a></h4>
<p>The name of a test library that is used when a library is imported is
the same as the name of the module or class implementing it. For
example, if you have a Python module <span
class="code">MyLibrary</span> (that is, the
@@ -7794,7 +7859,7 @@
</div>
</div>
<div class="section" id="providing-arguments-to-test-libraries">
-<h4><a class="toc-backref" href="#id326">Providing arguments to test libraries</a></h4>
+<h4><a class="toc-backref" href="#id328">Providing arguments to test libraries</a></h4>
<p>All test libraries implemented as classes can take arguments. These
arguments are specified in the Setting table after the library name,
and when Robot Framework creates an instance of the imported library,
@@ -7865,7 +7930,7 @@
</pre></div>
</div>
<div class="section" id="test-library-scope">
-<h4><a class="toc-backref" href="#id327">Test library scope</a></h4>
+<h4><a class="toc-backref" href="#id329">Test library scope</a></h4>
<p>Libraries implemented as classes can have an internal state, which can
be altered by keywords and with arguments to the constructor of the
library. Because the state can affect how keywords actually behave, it
@@ -7940,9 +8005,9 @@
</div>
</div>
<div class="section" id="creating-static-keywords">
-<h3><a class="toc-backref"
href="#id328">4.1.3   Creating static keywords</a></h3>
+<h3><a class="toc-backref"
href="#id330">4.1.3   Creating static keywords</a></h3>
<div class="section" id="keyword-names">
-<h4><a class="toc-backref" href="#id329">Keyword names</a></h4>
+<h4><a class="toc-backref" href="#id331">Keyword names</a></h4>
<p>When the static library API is used, Robot Framework uses reflection
to find out what methods the library implements. With <a
class="reference internal" href="#dynamic-library-api">dynamic library
API</a> and <a class="reference internal"
href="#hybrid-library-api">hybrid library API</a>, keyword names are
got from the
@@ -8033,7 +8098,7 @@
</table>
</div>
<div class="section" id="keyword-arguments">
-<h4><a class="toc-backref" href="#id330">Keyword arguments</a></h4>
+<h4><a class="toc-backref" href="#id332">Keyword arguments</a></h4>
<p>With a static and hybrid API, the information on how many arguments a
keyword needs is got directly from the method that implements it.
Libraries using the <a class="reference internal"
href="#dynamic-library-api">dynamic library API</a> have other means
for getting
@@ -8054,7 +8119,7 @@
<span class="k">def</span> <span
class="nf">multiple_arguments</span><span class="p">(</span><span
class="n">a1</span><span class="p">,</span> <span
class="n">a2</span><span class="p">,</span> <span
class="n">a3</span><span class="p">):</span>
<span class="k">print</span> <span class="s">"Keyword got
three arguments '</span><span class="si">%s</span><span
class="s">', '</span><span class="si">%s</span><span
class="s">' and '</span><span class="si">%s</span><span
class="s">'"</span> <span class="o">%</span> <span
class="p">(</span><span class="n">a1</span><span class="p">,</span>
<span class="n">a2</span><span class="p">,</span> <span
class="n">a3</span><span class="p">)</span>
</pre></div>
-<div class="section" id="id78">
+<div class="section" id="id79">
<h5>Default values</h5>
<p>It is often useful that some of the arguments that a keyword uses have
default values. Python and Java have different syntaxes for handling these
@@ -8154,7 +8219,7 @@
</tbody>
</table>
</div>
-<div class="section" id="id79">
+<div class="section" id="id80">
<h5>Variable number of arguments</h5>
<p>Robot Framework supports also keywords that take any number of
arguments. Similarly as with the default values, the actual syntax to use
@@ -8299,14 +8364,14 @@
</div>
</div>
<div class="section" id="communicating-with-robot-framework">
-<h3><a class="toc-backref"
href="#id331">4.1.4   Communicating with Robot Framework</a></h3>
+<h3><a class="toc-backref"
href="#id333">4.1.4   Communicating with Robot Framework</a></h3>
<p>After a method implementing a keyword is called, it can use any
mechanism to communicate with the system under test. It can then also
send messages to Robot Framework's log file, return information that
can be saved to variables and, most importantly, report if the
keyword passed or not.</p>
<div class="section" id="reporting-keyword-status">
-<h4><a class="toc-backref" href="#id332">Reporting keyword status</a></h4>
+<h4><a class="toc-backref" href="#id334">Reporting keyword status</a></h4>
<p>Reporting keyword status is done simply using exceptions. If a method
raises an exception, the keyword status is FAIL, and if it returns
normally, the status is PASS.</p>
@@ -8323,7 +8388,7 @@
message of the failed keyword, so it is not lost even if this happens.</p>
</div>
<div class="section" id="logging-information">
-<h4><a class="toc-backref" href="#id333">Logging information</a></h4>
+<h4><a class="toc-backref" href="#id335">Logging information</a></h4>
<p>Exception messages are not the only way to give information to the
users. In addition to that, methods can also send messages to <a
class="reference internal" href="#log-file">log
files</a> simply by writing to standard output (stdout) or standard
@@ -8404,7 +8469,7 @@
be used to make messages slightly more visible.</p>
</div>
<div class="section" id="returning-values">
-<h4><a class="toc-backref" href="#id334">Returning values</a></h4>
+<h4><a class="toc-backref" href="#id336">Returning values</a></h4>
<p>The final way for keywords to communicate back to the core framework
is returning information retrieved from the system under test or
generated by some other means. The returned values can be <a
class="reference internal" href="#return-values-from-keywords">assigned to
@@ -8520,9 +8585,9 @@
</div>
</div>
<div class="section" id="distributing-test-libraries">
-<h3><a class="toc-backref"
href="#id335">4.1.5   Distributing test libraries</a></h3>
+<h3><a class="toc-backref"
href="#id337">4.1.5   Distributing test libraries</a></h3>
<div class="section" id="documenting-libraries">
-<h4><a class="toc-backref" href="#id336">Documenting libraries</a></h4>
+<h4><a class="toc-backref" href="#id338">Documenting libraries</a></h4>
<p>A test library without documentation about what keywords it
contains and what those keywords do is rather useless. To ease
maintenance, it is highly recommended that library documentation is
@@ -8582,7 +8647,7 @@
at runtime.</p>
</div>
<div class="section" id="testing-libraries">
-<h4><a class="toc-backref" href="#id337">Testing libraries</a></h4>
+<h4><a class="toc-backref" href="#id339">Testing libraries</a></h4>
<p>Any non-trivial test library needs to be thoroughly tested to prevent
bugs in them. Of course, this testing should be automated to make it
easy to rerun tests when libraries are changed.</p>
@@ -8606,7 +8671,7 @@
the approaches.</p>
</div>
<div class="section" id="packaging-libraries">
-<h4><a class="toc-backref" href="#id338">Packaging libraries</a></h4>
+<h4><a class="toc-backref" href="#id340">Packaging libraries</a></h4>
<p>After a library is implemented, documented, and tested, it still needs
to be distributed to the users. With simple libraries consisting of a
single file, it is often enough to ask the users to copy that file
@@ -8625,7 +8690,7 @@
</div>
</div>
<div class="section" id="dynamic-library-api">
-<h3><a class="toc-backref"
href="#id339">4.1.6   Dynamic library API</a></h3>
+<h3><a class="toc-backref"
href="#id341">4.1.6   Dynamic library API</a></h3>
<p>The dynamic API is in most ways similar to the static API. For
example, reporting the keyword status, logging and returning values
works exactly the same way. Most importantly, there are no differences
@@ -8662,7 +8727,7 @@
component has several ways of creating keywords, and it is likely
that it already has a mechanism that suites your needs.</p>
<div class="section" id="getting-keyword-names">
-<h4><a class="toc-backref" href="#id340">Getting keyword names</a></h4>
+<h4><a class="toc-backref" href="#id342">Getting keyword names</a></h4>
<p>Dynamic libraries tell what keywords they implement with the
<span class="code">get_keyword_names</span> method. The method also
has the alias
<span class="code">getKeywordNames</span> that is recommended when
writing Java. This
@@ -8680,7 +8745,7 @@
static library, instead.</p>
</div>
<div class="section" id="running-keywords">
-<h4><a class="toc-backref" href="#id341">Running keywords</a></h4>
+<h4><a class="toc-backref" href="#id343">Running keywords</a></h4>
<p>Dynamic libraries have a special <span
class="code">run_keyword</span> (alias
<span class="code">runKeyword</span>) method for executing their
keywords. When a
keyword from a dynamic library is used in the test data, Robot
@@ -8710,7 +8775,7 @@
</pre></div>
</div>
<div class="section" id="getting-keyword-arguments">
-<h4><a class="toc-backref" href="#id342">Getting keyword arguments</a></h4>
+<h4><a class="toc-backref" href="#id344">Getting keyword arguments</a></h4>
<p>If a dynamic library only implements the <span
class="code">get_keyword_names</span> and
<span class="code">run_keyword</span> methods, Robot Framework does
not have any information
about the arguments that the implemented keywords need. For example,
@@ -8798,7 +8863,7 @@
need to have meaningful names.</p>
</div>
<div class="section" id="getting-keyword-documentation">
-<h4><a class="toc-backref" href="#id343">Getting keyword documentation</a></h4>
+<h4><a class="toc-backref" href="#id345">Getting keyword documentation</a></h4>
<p>The final special method that dynamic libraries can implement is
<span class="code">get_keyword_documentation</span> (alias
<span class="code">getKeywordDocumentation</span>). It takes a keyword
name as an
@@ -8813,7 +8878,7 @@
shown in test logs.</p>
</div>
<div class="section" id="summary">
-<h4><a class="toc-backref" href="#id344">Summary</a></h4>
+<h4><a class="toc-backref" href="#id346">Summary</a></h4>
<p>All special methods in the dynamic API are listed in the table
below. Method names are listed in the underscore format, but their
camelCase aliases function in exactly the same way.</p>
@@ -8871,19 +8936,19 @@
</div>
</div>
<div class="section" id="hybrid-library-api">
-<h3><a class="toc-backref" href="#id345">4.1.7   Hybrid
library API</a></h3>
+<h3><a class="toc-backref" href="#id347">4.1.7   Hybrid
library API</a></h3>
<p>The hybrid library API is, as its name implies, a hybrid between the
static API and the dynamic API. Just as with the dynamic API, it is
possible to implement a library using the hybrid API only as a class.</p>
-<div class="section" id="id84">
-<h4><a class="toc-backref" href="#id346">Getting keyword names</a></h4>
+<div class="section" id="id85">
+<h4><a class="toc-backref" href="#id348">Getting keyword names</a></h4>
<p>Keyword names are got in the exactly same way as with the dynamic
API. In practice, the library needs to have the
<span class="code">get_keyword_names</span> or <span
class="code">getKeywordNames</span> method returning
a list of keyword names that the library implements.</p>
</div>
-<div class="section" id="id85">
-<h4><a class="toc-backref" href="#id347">Running keywords</a></h4>
+<div class="section" id="id86">
+<h4><a class="toc-backref" href="#id349">Running keywords</a></h4>
<p>In the hybrid API, there is no <span
class="code">run_keyword</span> method for executing
keywords. Instead, Robot Framework uses reflection to find methods
implementing keywords, similarly as with the static API. A library
@@ -8925,7 +8990,7 @@
benefits compared to the static API.</p>
</div>
<div class="section" id="getting-keyword-arguments-and-documentation">
-<h4><a class="toc-backref" href="#id348">Getting keyword arguments and documentation</a></h4>
+<h4><a class="toc-backref" href="#id350">Getting keyword arguments and documentation</a></h4>
<p>When this API is used, Robot Framework uses reflection to find the
methods implementing keywords, similarly as with the static API. After
getting a reference to the method, it searches for arguments and
@@ -8933,8 +8998,8 @@
API. Thus there is no need for special methods for getting arguments
and documentation like there is with the dynamic API.</p>
</div>
-<div class="section" id="id87">
-<h4><a class="toc-backref" href="#id349">Summary</a></h4>
+<div class="section" id="id88">
+<h4><a class="toc-backref" href="#id351">Summary</a></h4>
<p>When implementing a test library in Python, the hybrid API has the same
dynamic capabilities as the actual dynamic API. A great benefit with
it is
that there is no need to have special methods for getting keyword
@@ -8953,22 +9018,22 @@
</div>
</div>
<div class="section" id="using-listener-interface">
-<h2><a class="toc-backref" href="#id319">4.2   Using
listener interface</a></h2>
+<h2><a class="toc-backref" href="#id321">4.2   Using
listener interface</a></h2>
<p>Robot Framework has a listener interface that can be used to receive
notifications about test execution. Listeners are classes with certain
special methods, and they can be implemented both with Python and
Java. Example uses of the listener interface include external test
monitors, sending a mail message when a test fails, and communicating with
other systems.</p>
-<div class="contents local topic" id="id88">
+<div class="contents local topic" id="id89">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#taking-listeners-into-use"
id="id350">4.2.1   Taking listeners into use</a></li>
-<li><a class="reference internal"
href="#available-listener-interface-methods"
id="id351">4.2.2   Available listener interface methods</a></li>
-<li><a class="reference internal" href="#listener-examples"
id="id352">4.2.3   Listener examples</a></li>
+<li><a class="reference internal" href="#taking-listeners-into-use"
id="id352">4.2.1   Taking listeners into use</a></li>
+<li><a class="reference internal"
href="#available-listener-interface-methods"
id="id353">4.2.2   Available listener interface methods</a></li>
+<li><a class="reference internal" href="#listener-examples"
id="id354">4.2.3   Listener examples</a></li>
</ul>
</div>
<div class="section" id="taking-listeners-into-use">
-<h3><a class="toc-backref" href="#id350">4.2.1   Taking
listeners into use</a></h3>
+<h3><a class="toc-backref" href="#id352">4.2.1   Taking
listeners into use</a></h3>
<p>Listeners are taken into use from the command line with the
<span class="opt">--listener</span> option, so that the name of the
listener is
given to it as an argument. The listener name is got from the name of
@@ -8985,7 +9050,7 @@
</pre>
</div>
<div class="section" id="available-listener-interface-methods">
-<h3><a class="toc-backref"
href="#id351">4.2.2   Available listener interface methods</a></h3>
+<h3><a class="toc-backref"
href="#id353">4.2.2   Available listener interface methods</a></h3>
<p>Robot Framework creates an instance of the listener class when test
execution starts. No arguments are given to the constructor of the
listener class. During the test execution, Robot Framework calls
@@ -9102,7 +9167,7 @@
</pre></div>
</div>
<div class="section" id="listener-examples">
-<h3><a class="toc-backref"
href="#id352">4.2.3   Listener examples</a></h3>
+<h3><a class="toc-backref"
href="#id354">4.2.3   Listener examples</a></h3>
<p>The first simple example is implemented with Python. It mainly
illustrates that using the listener interface is not very complicated.</p>
<div class="highlight"><pre><span class="k">class</span> <span
class="nc">SimpleListener</span><span class="p">:</span>
@@ -9199,7 +9264,7 @@
</div>
</div>
<div class="section" id="using-internal-apis">
-<h2><a class="toc-backref" href="#id320">4.3   Using
internal APIs</a></h2>
+<h2><a class="toc-backref" href="#id322">4.3   Using
internal APIs</a></h2>
<p>Robot Framework has some public APIs which are intended to help in developing
supporting tools or extending the processing of input or output data. These
APIs are implemented as Python modules, and as such can only be used from
@@ -9210,16 +9275,16 @@
more information are asking help from Robot Framework developers,
investigating existing <a class="reference internal"
href="#supporting-tools">supporting tools</a> that use these APIs, or
just taking a look at the source code of Robot Framework.</p>
-<div class="contents local topic" id="id89">
+<div class="contents local topic" id="id90">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#executed-test-data"
id="id353">4.3.1   Executed test data</a></li>
-<li><a class="reference internal" href="#test-execution"
id="id354">4.3.2   Test execution</a></li>
-<li><a class="reference internal" href="#parsed-test-data"
id="id355">4.3.3   Parsed test data</a></li>
-<li><a class="reference internal" href="#runnable-test-data"
id="id356">4.3.4   Runnable test data</a></li>
+<li><a class="reference internal" href="#executed-test-data"
id="id355">4.3.1   Executed test data</a></li>
+<li><a class="reference internal" href="#test-execution"
id="id356">4.3.2   Test execution</a></li>
+<li><a class="reference internal" href="#parsed-test-data"
id="id357">4.3.3   Parsed test data</a></li>
+<li><a class="reference internal" href="#runnable-test-data"
id="id358">4.3.4   Runnable test data</a></li>
</ul>
</div>
<div class="section" id="executed-test-data">
-<h3><a class="toc-backref"
href="#id353">4.3.1   Executed test data</a></h3>
+<h3><a class="toc-backref"
href="#id355">4.3.1   Executed test data</a></h3>
<p>This API consists of a method for reading Robot Framework output
file(s) into a
<span class="code">TestSuite</span> object that contains all the
relevant information about the
results of the test execution. Signature of method is <span class="code">TestSuite(outpath)</span>,
@@ -9267,7 +9332,7 @@
</pre></div>
</div>
<div class="section" id="test-execution">
-<h3><a class="toc-backref" href="#id354">4.3.2   Test execution</a></h3>
+<h3><a class="toc-backref" href="#id356">4.3.2   Test execution</a></h3>
<p>This API consists of <span class="code">run</span> method, which
can be used for starting the
test execution. Signature of the method is <span
class="code">run(*datasources, **options)</span>,
where <span class="code">datasources</span> are paths to files and
directories to be executed and
@@ -9288,7 +9353,7 @@
</div>
</div>
<div class="section" id="parsed-test-data">
-<h3><a class="toc-backref" href="#id355">4.3.3   Parsed
test data</a></h3>
+<h3><a class="toc-backref" href="#id357">4.3.3   Parsed
test data</a></h3>
<p>This API consists of a method for getting a <span
class="code">TestSuite</span> object that
contains parsed test data. The method is used like <span class="code">TestSuite(*datasources,
**options)</span>, where <span class="code">datasources</span> are
paths to files and directories
@@ -9308,7 +9373,7 @@
information about <span class="var">${CURDIR}</span>.</p>
</div>
<div class="section" id="runnable-test-data">
-<h3><a class="toc-backref"
href="#id356">4.3.4   Runnable test data</a></h3>
+<h3><a class="toc-backref"
href="#id358">4.3.4   Runnable test data</a></h3>
<p>This API consists of a method for parsing given input files into a runnable
<span class="code">TestSuite</span> object. This differs from a parsed
<span class="code">TestSuite</span> in that
variables and settings for suite(s) are processed.</p>
@@ -9319,27 +9384,27 @@
</div>
</div>
<div class="section" id="appendices">
-<h1><a class="toc-backref" href="#id140">5   Appendices</a></h1>
-<div class="contents local topic" id="id90">
+<h1><a class="toc-backref" href="#id141">5   Appendices</a></h1>
+<div class="contents local topic" id="id91">
<ul class="auto-toc simple">
-<li><a class="reference internal"
href="#all-available-settings-in-test-data"
id="id357">5.1   All available settings in test data</a></li>
-<li><a class="reference internal" href="#all-command-line-options"
id="id358">5.2   All command line options</a></li>
-<li><a class="reference internal" href="#supporting-tools"
id="id359">5.3   Supporting tools</a></li>
-<li><a class="reference internal" href="#documentation-formatting"
id="id360">5.4   Documentation formatting</a></li>
-<li><a class="reference internal" href="#time-format"
id="id361">5.5   Time format</a></li>
+<li><a class="reference internal"
href="#all-available-settings-in-test-data"
id="id359">5.1   All available settings in test data</a></li>
+<li><a class="reference internal" href="#all-command-line-options"
id="id360">5.2   All command line options</a></li>
+<li><a class="reference internal" href="#supporting-tools"
id="id361">5.3   Supporting tools</a></li>
+<li><a class="reference internal" href="#documentation-formatting"
id="id362">5.4   Documentation formatting</a></li>
+<li><a class="reference internal" href="#time-format"
id="id363">5.5   Time format</a></li>
</ul>
</div>
<div class="section" id="all-available-settings-in-test-data">
-<h2><a class="toc-backref" href="#id357">5.1   All
available settings in test data</a></h2>
-<div class="contents local topic" id="id91">
+<h2><a class="toc-backref" href="#id359">5.1   All
available settings in test data</a></h2>
+<div class="contents local topic" id="id92">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#id92"
id="id362">5.1.1   Setting table</a></li>
-<li><a class="reference internal" href="#test-case-table"
id="id363">5.1.2   Test Case table</a></li>
-<li><a class="reference internal" href="#id93"
id="id364">5.1.3   Keyword table</a></li>
+<li><a class="reference internal" href="#id93"
id="id364">5.1.1   Setting table</a></li>
+<li><a class="reference internal" href="#test-case-table"
id="id365">5.1.2   Test Case table</a></li>
+<li><a class="reference internal" href="#id94"
id="id366">5.1.3   Keyword table</a></li>
</ul>
</div>
-<div class="section" id="id92">
-<h3><a class="toc-backref"
href="#id362">5.1.1   Setting table</a></h3>
+<div class="section" id="id93">
+<h3><a class="toc-backref"
href="#id364">5.1.1   Setting table</a></h3>
<p>The Setting table is used to import test libraries, resource files and
variable files and to define metadata for test suites and test
cases. It can be included in test case files and resource files. Note
@@ -9415,7 +9480,7 @@
</table>
</div>
<div class="section" id="test-case-table">
-<h3><a class="toc-backref" href="#id363">5.1.2   Test
Case table</a></h3>
+<h3><a class="toc-backref" href="#id365">5.1.2   Test
Case table</a></h3>
<p>The settings in the Test Case table are always specific to the test
case for which they
are defined. Some of these settings override the default values
defined in the Settings table.</p>
<table border="1" class="tabular docutils">
@@ -9454,8 +9519,8 @@
</tbody>
</table>
</div>
-<div class="section" id="id93">
-<h3><a class="toc-backref"
href="#id364">5.1.3   Keyword table</a></h3>
+<div class="section" id="id94">
+<h3><a class="toc-backref"
href="#id366">5.1.3   Keyword table</a></h3>
<p>Settings in the Keyword table are specific to the user keyword for
which they are defined.</p>
<table border="1" class="tabular docutils">
<caption>Settings available in the Keyword table</caption>
@@ -9486,18 +9551,18 @@
</div>
</div>
<div class="section" id="all-command-line-options">
-<h2><a class="toc-backref" href="#id358">5.2   All
command line options</a></h2>
+<h2><a class="toc-backref" href="#id360">5.2   All
command line options</a></h2>
<p>This appendix lists all the command line options that are available
when <a class="reference internal"
href="#starting-test-execution">executing test cases</a> with <span
class="prog">pybot</span> or <span class="prog">jybot</span>, and when
<a class="reference internal"
href="#post-processing-outputs">post-processing outputs</a> with <span class="prog">rebot</span>.</p>
-<div class="contents local topic" id="id95">
+<div class="contents local topic" id="id96">
<ul class="auto-toc simple">
-<li><a class="reference internal"
href="#command-line-options-for-test-execution"
id="id365">5.2.1   Command line options for test execution</a></li>
-<li><a class="reference internal"
href="#command-line-options-for-post-processing-outputs"
id="id366">5.2.2   Command line options for
post-processing outputs</a></li>
+<li><a class="reference internal"
href="#command-line-options-for-test-execution"
id="id367">5.2.1   Command line options for test execution</a></li>
+<li><a class="reference internal"
href="#command-line-options-for-post-processing-outputs"
id="id368">5.2.2   Command line options for
post-processing outputs</a></li>
</ul>
</div>
<div class="section" id="command-line-options-for-test-execution">
-<h3><a class="toc-backref"
href="#id365">5.2.1   Command line options for test execution</a></h3>
+<h3><a class="toc-backref"
href="#id367">5.2.1   Command line options for test execution</a></h3>
<blockquote>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
@@ -9666,7 +9731,7 @@
</blockquote>
</div>
<div class="section" id="command-line-options-for-post-processing-outputs">
-<h3><a class="toc-backref"
href="#id366">5.2.2   Command line options for
post-processing outputs</a></h3>
+<h3><a class="toc-backref"
href="#id368">5.2.2   Command line options for
post-processing outputs</a></h3>
<blockquote>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
@@ -9813,86 +9878,86 @@
</div>
</div>
<div class="section" id="supporting-tools">
-<h2><a class="toc-backref"
href="#id359">5.3   Supporting tools</a></h2>
+<h2><a class="toc-backref"
href="#id361">5.3   Supporting tools</a></h2>
<p>In this appendix, the available supporting tools for Robot Framework
are described. Unless otherwise stated later in this chapter, the
tools can be downloaded from the <a class="reference external"
href="http://code.google.com/p/robotframework/wiki/SupportingTools">Robot
Framework supporting tools page</a>.</p>
-<div class="contents local topic" id="id96">
+<div class="contents local topic" id="id97">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#internal-tools"
id="id367">5.3.1   Internal tools</a><ul>
-<li><a class="reference internal"
href="#library-documentation-tool-libdoc-py" id="id368">Library
documentation tool -- libdoc.py</a></li>
-<li><a class="reference internal"
href="#historical-reporting-tool-risto-py" id="id369">Historical
reporting tool -- risto.py</a></li>
-<li><a class="reference internal"
href="#test-data-tidying-tool-robotidy-py" id="id370">Test data tidying
tool -- robotidy.py</a></li>
-<li><a class="reference internal"
href="#test-result-diffing-tool-robotdiff-py" id="id371">Test result
diffing tool -- robotdiff.py</a></li>
-<li><a class="reference internal"
href="#execution-time-reporting-tool-times2csv-py" id="id372">Execution
time reporting tool -- times2csv.py</a></li>
-<li><a class="reference internal"
href="#file-viewing-tool-fileviewer-py" id="id373">File viewing tool -- fileviewer.py</a></li>
-<li><a class="reference internal" href="#one-click-installer"
id="id374">One click installer</a></li>
-<li><a class="reference internal"
href="#test-status-checker-tool-statuschecker-py" id="id375">Test
status checker tool -- statuschecker.py</a></li>
+<li><a class="reference internal" href="#internal-tools"
id="id369">5.3.1   Internal tools</a><ul>
+<li><a class="reference internal"
href="#library-documentation-tool-libdoc-py" id="id370">Library
documentation tool -- libdoc.py</a></li>
+<li><a class="reference internal"
href="#historical-reporting-tool-risto-py" id="id371">Historical
reporting tool -- risto.py</a></li>
+<li><a class="reference internal"
href="#test-data-tidying-tool-robotidy-py" id="id372">Test data tidying
tool -- robotidy.py</a></li>
+<li><a class="reference internal"
href="#test-result-diffing-tool-robotdiff-py" id="id373">Test result
diffing tool -- robotdiff.py</a></li>
+<li><a class="reference internal"
href="#execution-time-reporting-tool-times2csv-py" id="id374">Execution
time reporting tool -- times2csv.py</a></li>
+<li><a class="reference internal"
href="#file-viewing-tool-fileviewer-py" id="id375">File viewing tool -- fileviewer.py</a></li>
+<li><a class="reference internal" href="#one-click-installer"
id="id376">One click installer</a></li>
+<li><a class="reference internal"
href="#test-status-checker-tool-statuschecker-py" id="id377">Test
status checker tool -- statuschecker.py</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#external-tools"
id="id376">5.3.2   External tools</a><ul>
-<li><a class="reference internal"
href="#test-data-editing-tool-robot-ide" id="id377">Test data editing
tool (Robot IDE)</a></li>
-<li><a class="reference internal"
href="#manual-test-execution-tool-mabot" id="id378">Manual test
execution tool (mabot)</a></li>
-<li><a class="reference internal" href="#core-for-java-test-libraries"
id="id379">Core for Java test libraries</a></li>
+<li><a class="reference internal" href="#external-tools"
id="id378">5.3.2   External tools</a><ul>
+<li><a class="reference internal"
href="#test-data-editing-tool-robot-ide" id="id379">Test data editing
tool (Robot IDE)</a></li>
+<li><a class="reference internal"
href="#manual-test-execution-tool-mabot" id="id380">Manual test
execution tool (mabot)</a></li>
+<li><a class="reference internal" href="#core-for-java-test-libraries"
id="id381">Core for Java test libraries</a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="internal-tools">
-<h3><a class="toc-backref"
href="#id367">5.3.1   Internal tools</a></h3>
+<h3><a class="toc-backref"
href="#id369">5.3.1   Internal tools</a></h3>
<div class="section" id="library-documentation-tool-libdoc-py">
-<h4><a class="toc-backref" href="#id368">Library documentation tool -- libdoc.py</a></h4>
+<h4><a class="toc-backref" href="#id370">Library documentation tool -- libdoc.py</a></h4>
<p><a class="reference external"
href="../../tools/libdoc/doc/libdoc.html">libdoc.py</a> is tool for
generating HTML or XML documentation from keywords of
a test library or a resource file.</p>
</div>
<div class="section" id="historical-reporting-tool-risto-py">
-<h4><a class="toc-backref" href="#id369">Historical reporting tool -- risto.py</a></h4>
+<h4><a class="toc-backref" href="#id371">Historical reporting tool -- risto.py</a></h4>
<p><a class="reference external"
href="../../tools/ristopy/doc/ristopy.html">risto.py</a> is a tool for
generating graphs about historical statistics
of test executions.</p>
</div>
<div class="section" id="test-data-tidying-tool-robotidy-py">
-<h4><a class="toc-backref" href="#id370">Test data tidying tool -- robotidy.py</a></h4>
+<h4><a class="toc-backref" href="#id372">Test data tidying tool -- robotidy.py</a></h4>
<p><a class="reference external"
href="../../tools/robotidy/doc/robotidy.html">robotidy.py</a> is a tool
for cleaning Robot Framework test data, changing test
data format between HTML and TSV and fixing inline comments to format supported
by Robot IDE.</p>
</div>
<div class="section" id="test-result-diffing-tool-robotdiff-py">
-<h4><a class="toc-backref" href="#id371">Test result diffing tool -- robotdiff.py</a></h4>
+<h4><a class="toc-backref" href="#id373">Test result diffing tool -- robotdiff.py</a></h4>
<p><a class="reference external"
href="../../tools/robotdiff/doc/robotdiff.html">robotdiff.py</a> is a
tool for generating diff reports from Robot
Framework output files.</p>
</div>
<div class="section" id="execution-time-reporting-tool-times2csv-py">
-<h4><a class="toc-backref" href="#id372">Execution time reporting tool
-- times2csv.py</a></h4>
+<h4><a class="toc-backref" href="#id374">Execution time reporting tool
-- times2csv.py</a></h4>
<p><a class="reference external"
href="../../tools/times2csv/doc/times2csv.html">times2csv.py</a> is a
tool for generating start, end and elapsed
time information about suites, tests and keywords in CSV format.</p>
</div>
<div class="section" id="file-viewing-tool-fileviewer-py">
-<h4><a class="toc-backref" href="#id373">File viewing tool -- fileviewer.py</a></h4>
+<h4><a class="toc-backref" href="#id375">File viewing tool -- fileviewer.py</a></h4>
<p><a class="reference external"
href="../../tools/fileviewer/doc/fileviewer.html">fileviewer.py</a> is
a graphical tool implementing UNIX <span class="cli">tail</span> -like
functionality. It is especially designed to view <a class="reference
internal" href="#debug-file">debug files</a></p>
</div>
<div class="section" id="one-click-installer">
-<h4><a class="toc-backref" href="#id374">One click installer</a></h4>
+<h4><a class="toc-backref" href="#id376">One click installer</a></h4>
<p><a class="reference external"
href="../../tools/oneclickinstaller/doc/oneclickinstaller.html">One
click installer</a> is an <a class="reference external"
href="http://www.autoitscript.com/autoit3/">AutoIT</a> script that
installs Robot
Framework and its dependencies.</p>
</div>
<div class="section" id="test-status-checker-tool-statuschecker-py">
-<h4><a class="toc-backref" href="#id375">Test status checker tool -- statuschecker.py</a></h4>
+<h4><a class="toc-backref" href="#id377">Test status checker tool -- statuschecker.py</a></h4>
<p><a class="reference external"
href="../../tools/statuschecker/doc/statuschecker.html">statuschecker.py</a>
is a tool for verifying that test case statuses and messages
and also keyword log messages are as expected.</p>
</div>
</div>
<div class="section" id="external-tools">
-<h3><a class="toc-backref"
href="#id376">5.3.2   External tools</a></h3>
+<h3><a class="toc-backref"
href="#id378">5.3.2   External tools</a></h3>
<div class="section" id="test-data-editing-tool-robot-ide">
-<h4><a class="toc-backref" href="#id377">Test data editing tool (Robot IDE)</a></h4>
+<h4><a class="toc-backref" href="#id379">Test data editing tool (Robot IDE)</a></h4>
<p>Robot IDE is a standalone tool for editing test data. It helps in
creating, editing and maintaining of Robot Framework test data.</p>
<p>More information will be added as soon as Robot IDE project is
made publicly available.</p>
</div>
<div class="section" id="manual-test-execution-tool-mabot">
-<h4><a class="toc-backref" href="#id378">Manual test execution tool (mabot)</a></h4>
+<h4><a class="toc-backref" href="#id380">Manual test execution tool (mabot)</a></h4>
<p><span class="prog">mabot</span> is a standalone tool for reporting
manual test execution results.
It enables storing and reporting manual test cases along with
automated Robot
Framework test cases.</p>
@@ -9900,7 +9965,7 @@
made publicly available.</p>
</div>
<div class="section" id="core-for-java-test-libraries">
-<h4><a class="toc-backref" href="#id379">Core for Java test libraries</a></h4>
+<h4><a class="toc-backref" href="#id381">Core for Java test libraries</a></h4>
<p>Javalib-core is an external component that simplifies creation of
larger Java
test libraries by offering several dynamic ways of resolving available keywords
at runtime. For more information, see
@@ -9909,23 +9974,23 @@
</div>
</div>
<div class="section" id="documentation-formatting">
-<h2><a class="toc-backref"
href="#id360">5.4   Documentation formatting</a></h2>
+<h2><a class="toc-backref"
href="#id362">5.4   Documentation formatting</a></h2>
<p>It is possible to use simple HTML formatting with <a
class="reference internal"
href="#test-suite-name-and-documentation">test suite</a>,
<a class="reference internal"
href="#test-case-name-and-documentation">test case</a> and <a
class="reference internal"
href="#user-keyword-name-and-documentation">user keyword</a>
documentation in the test data, as well
as when <a class="reference internal"
href="#documenting-libraries">documenting test libraries</a>. The
formatting is similar to
the style used in most wikis, and it is designed to be understandable
both as plain text and after the HTML transformation.</p>
-<div class="contents local topic" id="id111">
+<div class="contents local topic" id="id112">
<ul class="auto-toc simple">
-<li><a class="reference internal" href="#representing-newlines"
id="id380">5.4.1   Representing newlines</a></li>
-<li><a class="reference internal" href="#bold-and-italic"
id="id381">5.4.2   Bold and italic</a></li>
-<li><a class="reference internal" href="#urls" id="id382">5.4.3   URLs</a></li>
-<li><a class="reference internal" href="#tables" id="id383">5.4.4   Tables</a></li>
-<li><a class="reference internal" href="#horizontal-ruler"
id="id384">5.4.5   Horizontal ruler</a></li>
+<li><a class="reference internal" href="#representing-newlines"
id="id382">5.4.1   Representing newlines</a></li>
+<li><a class="reference internal" href="#bold-and-italic"
id="id383">5.4.2   Bold and italic</a></li>
+<li><a class="reference internal" href="#urls" id="id384">5.4.3   URLs</a></li>
+<li><a class="reference internal" href="#tables" id="id385">5.4.4   Tables</a></li>
+<li><a class="reference internal" href="#horizontal-ruler"
id="id386">5.4.5   Horizontal ruler</a></li>
</ul>
</div>
<div class="section" id="representing-newlines">
-<h3><a class="toc-backref"
href="#id380">5.4.1   Representing newlines</a></h3>
+<h3><a class="toc-backref"
href="#id382">5.4.1   Representing newlines</a></h3>
<p>The documentation used for test suites, test cases and keywords is
subject to <a class="reference internal"
href="#test-data-syntax">general parsing rules</a> of the test data.
This means that
normal newlines are not preserved, and dividing documentation into lines
@@ -9956,7 +10021,7 @@
</pre></div>
</div>
<div class="section" id="bold-and-italic">
-<h3><a class="toc-backref" href="#id381">5.4.2   Bold
and italic</a></h3>
+<h3><a class="toc-backref" href="#id383">5.4.2   Bold
and italic</a></h3>
<p>Bold text can be created by having an asterisk before and after the
selected word or words, for example <span class="code">*this is
bold*</span>. Italic
style works similarly, but the special character to use is an
@@ -9995,12 +10060,12 @@
</tr>
</table></div>
<div class="section" id="urls">
-<h3><a class="toc-backref" href="#id382">5.4.3   URLs</a></h3>
+<h3><a class="toc-backref" href="#id384">5.4.3   URLs</a></h3>
<p>All strings that look like URLs are automatically converted into a
clickable link. For example, <span class="code">http://some.url</span>
turns into link.</p>
</div>
<div class="section" id="tables">
-<h3><a class="toc-backref" href="#id383">5.4.4   Tables</a></h3>
+<h3><a class="toc-backref" href="#id385">5.4.4   Tables</a></h3>
<p>Tables are created using the pipe character with whitespace around it
as a cell boundary and the newline as a row separator. In library
documentations normal newlines are enough, but in test suite, test
@@ -10038,7 +10103,7 @@
</table>
</div>
<div class="section" id="horizontal-ruler">
-<h3><a class="toc-backref"
href="#id384">5.4.5   Horizontal ruler</a></h3>
+<h3><a class="toc-backref"
href="#id386">5.4.5   Horizontal ruler</a></h3>
<p>Horizontal rulers (the <hr> tag) make it possible to separate larger
sections from each others, and they can be created by having three
hyphens alone in a line. With documentations in the test data literal
@@ -10053,7 +10118,7 @@
</div>
</div>
<div class="section" id="time-format">
-<h2><a class="toc-backref" href="#id361">5.5   Time format</a></h2>
+<h2><a class="toc-backref" href="#id363">5.5   Time format</a></h2>
<p>Robot Framework has its own time format that is used by several
keywords (for example <span class="name">Sleep</span> and <span
class="name">Wait Until Keyword
Succeeds</span>) as well as <a class="reference internal"
href="#test-case-timeout">test case</a> and <a class="reference
internal" href="#user-keyword-timeout">user keyword timeouts</a>. This
@@ -10107,7 +10172,7 @@
<div class="footer">
<hr class="footer" />
<p>Generated by <a class="reference external"
href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>.
Syntax highlighting by <a class="reference external" href="http://pygments.org/">Pygments</a>.</p>
-<p>Generated on: 2008-07-22 09:53 UTC.
+<p>Generated on: 2008-07-22 11:06 UTC.
</p>

</div>

Modified: trunk/doc/userguide/src/CreatingTestData/UsingTestLibraries.txt
==============================================================================
--- trunk/doc/userguide/src/CreatingTestData/UsingTestLibraries.txt (original)
+++ trunk/doc/userguide/src/CreatingTestData/UsingTestLibraries.txt Tue
Jul 22 04:07:21 2008
@@ -9,7 +9,6 @@
provide. `Creating test libraries`_ is described in a separate
section.

-
.. contents::
:depth: 2
:local:
@@ -46,13 +45,13 @@
Library ${LIBRARY} \ \
========= =================== ======= =======

-
It is possible to import test libraries in `test case files`_,
`resource files`_ and `test suite initialization files`_. In all these
cases, all the keywords in the imported library are available in that
file. With resource files, those keywords are also available in other
files using them.

+
Using Import Library keyword
''''''''''''''''''''''''''''

@@ -80,15 +79,58 @@
Library search path
'''''''''''''''''''

-Robot Framework can import a library only if the library class or
-module can be found from the library search path. Basically, this
-means that the library code and all its possible dependencies must be
-in :code:`PYTHONPATH` or, when running tests on Jython, in a
+The most common way to specify a test library to import is using its
+name, like it has been done in all the examples in this section. In
+these cases Robot Framework tries to find the class or module
+implementing the library from the *library search path*. Basically,
+this means that the library code and all its possible dependencies
+must be in :code:`PYTHONPATH` or, when running tests on Jython, in a
:code:`CLASSPATH`. `Setting the library search path`__ is explained in
-a section of its own, and well-developed libraries either do that
-automatically or have clear instructions on how to do it.
+a section of its own. Libraries can also set the search path
+automatically or have special instructions on how to do it. All
+`standard libraries`_, for example, are in the library search path
+automatically.
+
+The biggest benefit of this approach is that when the library search
+path has been configured, often using a `custom start-up script`__,
+normal users do not need to think where libraries actually are
+installed. The drawback is that getting your own, possible
+very simple, libraries into the search path may require some
+additional configuration.

__ `Adjusting library search path`_
+__ `Creating start-up scripts`_
+
+
+Using physical path to library
+''''''''''''''''''''''''''''''
+
+Another mechanism for specifying the library to import is using a
+path to it in the file system. This path is considered relative to the
+directory where current test data file is situated similarly as paths
+to `resource and variable files`_. The main benefit of this approach
+is that there is no need to configure the library search path.
+
+If the library is a file, the path to it must contain extension. For
+Python libraries the extension is naturally :path:`.py` and for Java
+libraries it can either be :path:`.class` or :path:`.java`, but the
+class file must always be available. If Python library is implemented
+as a directory, the path to it must have a trailing forward slash
+(:path:`/`). Importing Java libraries in JAR packages is not possible
+using this mechanism. Following examples demonstrate these different
+usages.
+
+.. table:: Importing test libraries using physical paths to them
+ :class: example
+
+ ========= =========================== ======== =========
+ Setting Value Value Value
+ ========= =========================== ======== =========
+ Library PythonLib.py \ \
+ Library /absolute/path/JavaLib.java \ \
+ Library relative/path/PythonDirLib/ possible arguments
+ Library ${RESOURCES}/Example.class \ \
+ ========= =========================== ======== =========