Revision: 3953
Author: jussi.ao.malinen
Date: Fri Aug 27 01:51:24 2010
Log: userguide cleanup
http://code.google.com/p/robotframework/source/detail?r=3953
Modified:
/trunk/doc/userguide/src/ExecutingTestCases/BasicUsage.txt
/trunk/doc/userguide/src/ExecutingTestCases/ConfiguringExecution.txt
/trunk/doc/userguide/src/ExecutingTestCases/OutputFiles.txt
/trunk/doc/userguide/src/ExecutingTestCases/TestExecution.txt
/trunk/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.txt
=======================================
--- /trunk/doc/userguide/src/ExecutingTestCases/BasicUsage.txt Thu Aug 26
06:38:46 2010
+++ /trunk/doc/userguide/src/ExecutingTestCases/BasicUsage.txt Fri Aug 27
01:51:24 2010
@@ -51,7 +51,7 @@
__ `Where files are installed`_
__ `Modifying Java startup parameters`_
-Regardless of the runner script, a path (or paths) to the test data to be
+Regardless of the runner script, the path (or paths) to the test data to be
executed is given as an argument. Additionally, different command line
options can be used to alter the test execution or generated
outputs in some way.
@@ -90,9 +90,9 @@
catenating them together with an ampersand (&) and spaces. For example,
the name of the top-level suite in the first example below is
:name:`My Tests & Your Tests`. These automatically created names are
-seldom very good and they are often quite long. In most cases, it
-is thus better to use the :opt:`--name` option for overriding it, as
-in the second example below::
+often quite long and complicated. In most cases, it is thus better to
+use the :opt:`--name` option for overriding it, as in the second
+example below::
pybot my_tests.html your_tests.html
pybot --name Example path/to/tests/pattern_*.html
@@ -103,8 +103,8 @@
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. This section explains the option syntax, and what
-options actually exist and how they can be used is
-discussed elsewhere in this chapter.
+options actually exist. How they can be used is discussed elsewhere
+in this chapter.
Using options
'''''''''''''
@@ -141,7 +141,7 @@
name. Both short and long options accept the value separated
from the option name with a space, as in :cli:`--include tag`
or :cli:`-i tag`. With long options, the separator can also be the
-equals sign, as in :cli:`--include=tag`, and with short options the
+equals sign, for example :cli:`--include=tag`, and with short options the
separator can be omitted, as in :cli:`-itag`.
Some options can be specified several times. For example,
@@ -191,9 +191,9 @@
''''''''''''''''''''''
The command line output is very limited, and separate output files are
-normally needed for investigating the test execution. As the example
+normally needed for investigating the test results. As the example
above shows, three output files are generated by default. The first
-one is in the XML format and contains all the information about test
+one is in XML format and contains all the information about test
execution. The second is a higher-level report and the third is a more
detailed log file. These files and other possible output files are
discussed in more detail in the section `Different output files`_.
@@ -202,10 +202,9 @@
''''''''''''
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
-the execution starts successfully and no `critical test`_
-fail. Possible return codes are explained in the table below.
+system running them using return codes. When the execution starts
+successfully and no `critical test`_ fail, the return code is zero.
+All possible return codes are explained in the table below.
.. table:: Possible return codes
:class: tabular
@@ -308,7 +307,7 @@
The following examples make the syntax more clear. In the
first example, the metadata :opt:`X` gets the value :code:`Value with
-spaces`, and in the second variable :var:`${VAR}` is assigned to
+spaces`, and in the second example variable :var:`${VAR}` is assigned to
:code:`"Hello, world!"`::
--escape space:_ --metadata X:Value_with_spaces
@@ -455,8 +454,7 @@
Implementing this using Windows batch files is slightly more complicated.
The
difficult part is setting the variable containing the needed JARs inside a
For
loop, because, for some reason, that is not possible without a helper
-function. There is no need to use :prog:`call`, because only one batch
-file is executed.
+function.
.. sourcecode:: bat
=======================================
--- /trunk/doc/userguide/src/ExecutingTestCases/ConfiguringExecution.txt
Tue Aug 24 04:55:40 2010
+++ /trunk/doc/userguide/src/ExecutingTestCases/ConfiguringExecution.txt
Fri Aug 27 01:51:24 2010
@@ -83,9 +83,8 @@
specified tags by separating the tags either with :code:`&` or
:code:`AND` (case-sensitive). Starting from Robot Framework 2.1.3, only
tests
with a certain tag, but without any others, can be selected by separating
these
-tags with :code:`NOT` (case-sensitive). In case any of the patterns between
-multiple :code:`NOT` is matching, the test case is not selected. Patterns
can be
-`simple patterns`_ or :code:`AND` rule.
+tags with :code:`NOT` (case-sensitive). If any of the patterns between
+multiple :code:`NOT` is matching, the test case is not selected.
::
@@ -240,7 +239,7 @@
before the test execution. Jython actually does not use PYTHONPATH
environment variable normally, but Robot Framework ensures that
locations listed in it are added into the library search path
-regardless the interpreter.
+regardless of the interpreter.
Setting CLASSPATH
'''''''''''''''''
@@ -290,8 +289,8 @@
~~~~~~~
Robot Framework supports so called *dry run* mode where the tests are
-run normally otherwise, but the keywords coming from test libraries
-are not executed at all. The dry rum mode can be used to validate the
+run normally otherwise, but the keywords coming from the test libraries
+are not executed at all. The dry run mode can be used to validate the
test data; if the dry run passes, the data should be syntactically
correct. This mode is triggered using option :opt:`--runmode DryRun`
(case-insensitive) and it is supported starting from Robot Framework
=======================================
--- /trunk/doc/userguide/src/ExecutingTestCases/OutputFiles.txt Mon Aug 23
07:16:42 2010
+++ /trunk/doc/userguide/src/ExecutingTestCases/OutputFiles.txt Fri Aug 27
01:51:24 2010
@@ -1,7 +1,7 @@
Created outputs
---------------
-Several output files are created when tests are executed, and most of
+Several output files are created when tests are executed, and all 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.
@@ -36,19 +36,24 @@
Output file
'''''''''''
-Output files contain all the test execution results in the XML
+Output files contain all the test execution results in XML
format. Log_, report_, and summary_ files are generated based on
output files, and output files can also be `combined and otherwise
post-processed`__ after the test execution.
The command line option :opt:`--output (-o)` determines where
output files are created. Output files are always created when tests
-are executed, and the default name for them is
-:path:`output.xml`. When post-processing outputs, new output files are
-not created unless this option is explicitly used.
+are executed, and unless outputs are `splitted`__, only one output file
+is created. The default name for the output file is :path:`output.xml`.
+If outputs are splitted to several output files, they are named by
+postfixing the name of the first output file with sequence numbers. When
+post-processing outputs, new output files are not created unless
+:opt:`--output (-o)` option is explicitly used.
__ `Post-processing outputs`_
+__ `Splitting outputs`_
+
Log file
''''''''
@@ -68,13 +73,13 @@
:target: src/ExecutingTestCases/log_passed.html
:width: 500
- An example of beginning of log file
+ An example of beginning of a log file
.. figure:: src/ExecutingTestCases/log_failed.png
:target: src/ExecutingTestCases/log_failed.html
:width: 500
- An example of log file with keyword details visible
+ An example of a log file with keyword details visible
Report file
'''''''''''
@@ -84,7 +89,7 @@
as well as a list of all executed test cases. When both reports and
logs are generated, the report has links to the log file for easy
navigation to more detailed information. It is easy to see the
-overall test execution status from reports, because their background
+overall test execution status from report, because its background
color is green, if all `critical tests`_ pass, and bright red
otherwise.
@@ -198,8 +203,8 @@
element's :code:`background` CSS property. The value is used as-is and
can be a HTML color name (e.g. :code:`red`), a hexadecimal value
(e.g. :code:`#F00`), or an RGB value (e.g. :code:`rgb(255,0,0)`. The
-default green and red colors are actually specified using hexadecimal
-values and they are :code:`#9F6` and :code:`#F33`, respectively.
+default green and red colors are specified using hexadecimal
+values :code:`#9F6` and :code:`#F33`, respectively.
Log levels
~~~~~~~~~~
@@ -231,7 +236,7 @@
logged using this level automatically.
:msg:`TRACE`
- Another debugging level. The keyword arguments and return values
+ More detailed debugging level. The keyword arguments and return values
are automatically logged using this level.
__ `Logging information`_
@@ -268,7 +273,7 @@
''''''''
When executing a large number of test cases, the size of log files can
-increase to the extent that opening them into browsers is
+increase to the extent that opening them into a browser is
slow. Additionally, since log files can be created only after output
files are ready, they are available only after the test
execution. This is not a problem if the test execution time is short,
@@ -279,7 +284,7 @@
problems. First of all, splitting logs means that individual log files
are smaller and thus faster to open. If outputs are split while
executing test cases, the lower-level log files are also created
-immediateay when the equivelent output files are ready. Notifications
+immediately when the equivalent output files are ready. Notifications
about created files can be received through the `listener
interface`_, and `automatic variables`_ :var:`${LOG_FILE}` and
:var:`${OUTPUT_FILE}` always contain the path to the current file.
@@ -368,7 +373,7 @@
In this example, splitting is done from the second level. The table below
again lists created the files, and because :prog:`rebot` does not create
new
-output files by default, they are not listed in the table either.
+output files by default, they are not listed in the table.
.. table:: All output files created in the second example
:class: tabular
=======================================
--- /trunk/doc/userguide/src/ExecutingTestCases/TestExecution.txt Tue Aug
24 11:37:09 2010
+++ /trunk/doc/userguide/src/ExecutingTestCases/TestExecution.txt Fri Aug
27 01:51:24 2010
@@ -27,10 +27,11 @@
tests they are executed one-by-one, and if it has suites they are
executed recursively in depth-first order. When an individual test
case is executed, the keywords it contains are run in a
-sequence. Normally the execution ends if any of the keywords fails,
-but it is also possible to `continue after failures`__. The exact
`execution
-order`_ and how possible `setups and teardowns`_ affect the execution
-are discussed in the following sections.
+sequence. Normally the execution of the current test ends if any
+of the keywords fails, but it is also possible to
+`continue after failures`__. The exact `execution order`_ and how
+possible `setups and teardowns`_ affect the execution are discussed
+in the following sections.
__ `Test suite directories`_
__ `Selecting test cases`_
@@ -79,8 +80,8 @@
Test setup
``````````
-Possible test setup is executed before the keywords a test case
-has. If the setup fails, the keywords are not executed. The main use
+Possible test setup is executed before the keywords of the test case.
+If the setup fails, the keywords are not executed. The main use
for test setups is setting up the environment for that particular test
case.
@@ -88,7 +89,7 @@
`````````````
Possible test teardown is executed after the test case has been
-executed otherwise. It is executed regardless of the test status and also
+executed. It is executed regardless of the test status and also
if the setup of the test has failed.
Similarly as suite teardown, test teardowns are used mainly for
@@ -129,10 +130,9 @@
Normally test cases are stopped immediately when any of their keywords
fail. This behavior shortens test execution time and prevents
subsequent keywords hanging or otherwise causing problems if the
-system under test is in unstable state. The biggest drawbacks are that
often
+system under test is in unstable state. This has the drawback that often
subsequent keywords would give more information about the state of the
-system, and in teardowns all the cleanup keywords may not be
-executed.
+system.
Before Robot Framework 2.5 the only way to handle failures so that
test execution is not terminated immediately was using `BuiltIn
@@ -221,7 +221,7 @@
'''''''''''''
On Unix-like machines it is possible to terminate test execution
-using signals :code:`INT` and :code:`TERM`. These signals can be send
+using signals :code:`INT` and :code:`TERM`. These signals can be sent
from the command line using :prog:`kill` command, and sending signals can
also be easily automated.
@@ -241,8 +241,8 @@
'''''''''''''''''''''''''
If option :opt:`--runmode` is used with value :opt:`ExitOnFailure`
-(case-insensitive), the test execution stops immediately if a `critical
-test`_ fails.
+(case-insensitive), the execution of tests stops immediately if
+a `critical test`_ fails and the remaining tests are marked as failed.
Handling teardowns
''''''''''''''''''
=======================================
---
/trunk/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.txt
Thu Aug 26 23:39:25 2010
+++
/trunk/doc/userguide/src/ExtendingRobotFramework/CreatingTestLibraries.txt
Fri Aug 27 01:51:24 2010
@@ -52,9 +52,9 @@
Static API
The simplest approach is having a module (in Python) or a class
- (in Python or Java) with methods the names of which map more or less
- directly to `keyword names`_. Keywords also take the same `arguments`__
as
- the code implementing them. Keywords `report failures`__ with
+ (in Python or Java) with methods which map directly to
+ `keyword names`_. Keywords also take the same `arguments`__ as
+ the methods implementing them. Keywords `report failures`__ with
exceptions, `log`__ by writing to standard output and can `return
values`__ using the :code:`return` statement.
@@ -139,8 +139,8 @@
similarly as with `keyword arguments`_, with the exception that there
is no variable argument support for Java libraries. Arguments passed
to the library, as well as the library name itself, can be specified
-using variables, so it is possible to alter them, for example, from the
command
-line.
+using variables, so it is possible to alter them, for example, from the
+command line.
.. table:: Importing a test library with arguments
:class: example
@@ -191,7 +191,7 @@
be altered by keywords and with arguments to the constructor of the
library. Because the state can affect how keywords actually behave, it
is important to make sure that changes in one test case do not
-accidentally affect other test cases. This kind of dependencies may
+accidentally affect other test cases. These kind of dependencies may
create hard-to-debug problems, for example, when new test cases are
added and they use the library inconsistently.
@@ -282,9 +282,9 @@
:code:`ROBOT_LIBRARY_VERSION`, similarly as `test library scope`_ is
read from :code:`ROBOT_LIBRARY_SCOPE`. If
:code:`ROBOT_LIBRARY_VERSION` does not exist, information is tried to
-be read from :code:`__version__` attribute. These attributes must be a
+be read from :code:`__version__` attribute. These attributes must be
class or module attributes, depending whether the library is
-implemented as a class or a module. For Java libraries, the version
+implemented as a class or a module. For Java libraries the version
attribute must be declared as :code:`static final`.
An example Python module using :code:`__version__`:
@@ -357,9 +357,7 @@
The example below illustrates how the example libraries above can be
used. If you want to try this yourself, make sure that the library is
-in the `library search path`_. Note that in the subsequent examples all
-boilerplate, such as taking a library into use and creating a test
-case, is excluded.
+in the `library search path`_.
.. table:: Using simple example library
:class: example
@@ -385,7 +383,7 @@
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 `dynamic library API`_ have other means for getting
+Libraries using the `dynamic library API`_ have other means for sharing
this information, so this section is not relevant to them.
The most common and also simplest situation is when a keyword needs an
@@ -433,7 +431,7 @@
The first example keyword above can be used either with zero or one
arguments. If no arguments are given, :code:`arg` gets the value
:code:`default`. If there is one argument, :code:`arg` gets that value,
-and calling the keyword with any other number of arguments fails. In the
+and calling the keyword with more than one argument fails. In the
second example, one argument is always required, but the second and
the third one have default values, so it is possible to use the keyword
with one to three arguments.
@@ -491,10 +489,9 @@
Variable number of arguments with Python
````````````````````````````````````````
-Python itself has a good support for methods accepting any
-number of arguments. The same syntax works in libraries and, as
-the examples below show, it can also be combined with other ways of
-specifying arguments:
+Python supports methods accepting any number of arguments. The same
+syntax works in libraries and, as the examples below show, it can also
+be combined with other ways of specifying arguments:
.. sourcecode:: python
@@ -531,35 +528,43 @@
Variable number of arguments with Java
``````````````````````````````````````
-In Java, there is no syntax for a variable number of arguments, but Robot
-Framework has its own support for them. If the last argument in a keyword
-signature is an array, all leftover arguments are packed into
-it. This also works, if the keyword is used with one argument less than
-the actual number of arguments in the signature - in this case the
-array at the end will be empty.
-
-This system has one limitation: it only works if the method has one
-signature. Thus it is not possible to have a Java keyword that has
-both the default values and a variable number of arguments. Of course,
-having the required values with a variable number of arguments is
-possible, as the examples below illustrate:
+Robot supports Java varargs syntax for defining variable number of
arguments.
+Robot also will translate an array as the last argument in a keyword
signature as
+a list of variable number of arguments. In this case, all leftover
arguments to the
+keyword are packed into the list. This also works if the keyword is used
with one
+argument less than the actual number of arguments in the signature - in
this case
+the array at the end will be empty.
+
+Robot's support for variable number of arguments in Java has one
limitation:
+it only works if the method has only one signature. Thus it is not
possible to have a
+Java keyword that has both the default values and a variable number of
arguments.
+Of course, having a number of required arguments is still possible, as the
+examples below illustrate:
.. sourcecode:: java
- public void anyArguments(String[] args) {
+ public void anyNumberOfArguments(String... varargs) {
System.out.println("Got arguments:");
- for (int i; i < args.length; i++) {
- System.out.println(args[i]);
+ for (String arg: varargs) {
+ System.out.println(arg);
}
}
- public void oneRequired(String required, String[] others) {
+ public void oneArgumentRequired(String required, String... others) {
System.out.println("Required: " + required + "\nOthers:");
- for (int i; i < others.length; i++) {
- System.out.println(others[i]);
+ for (String arg: others) {
+ System.out.println(arg);
}
}
+ public void usingAnArray(String[] args) {
+ System.out.println("Got arguments:");
+ for (String arg: args) {
+ System.out.println(arg);
+ }
+ }
+
+
Argument types
''''''''''''''
