8000 Document RPA functionality. · pythonthings/robotframework@8c12fe1 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8c12fe1

Browse files
pekkaklarckpekkaklarck
committed
Document RPA functionality.
Fixes robotframework#2855. See also robotframework#2788 that introduced the RPA functionality.
1 parent 0618585 commit 8c12fe1

File tree

11 files changed

+171
-18
lines changed

11 files changed

+171
-18
lines changed

‎doc/userguide/src/Appendices/AvailableSettings.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ importing libraries, resources, and variables.
5050
+-----------------+--------------------------------------------------------+
5151
| Test Timeout | Used for specifying a default `test case timeout`_. |
5252
+-----------------+--------------------------------------------------------+
53+
| Task Setup, | Aliases for Test Setup, Test Teardown, Test Template |
54+
| Task Teardown, | and Test Timeout, respectively, that can be used when |
55+
| Task Template, | `creating tasks`_. |
56+
| Task Timeout | |
57+
+-----------------+--------------------------------------------------------+
5358

5459
.. note:: All setting names can optionally include a colon at the end, for
5560
example :setting:`Documentation:`. This can make reading the settings easier
@@ -65,6 +70,8 @@ The settings in the Test Case table are always specific to the test
6570
case for which they are defined. Some of these settings override the
6671
default values defined in the Settings table.
6772

73+
Exactly same settings are available when `creating tasks`_ in the Task table.
74+
6875
.. table:: Settings available in the Test Case table
6976
:class: tabular
7077

‎doc/userguide/src/Appendices/CommandLineOptions.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,14 @@ are listed.
1313
Command line options for test execution
1414
---------------------------------------
1515

16+
--rpa Turn on `generic automation`_ mode.
1617
-F, --extension <value> `Parse only these files`_ when executing a directory.
1718
-N, --name <name> `Sets the name`_ of the top-level test suite.
1819
-D, --doc <document> `Sets the documentation`_ of the top-level test suite.
1920
-M, --metadata <name:value> `Sets free metadata`_ for the top level test suite.
2021
-G, --settag <tag> `Sets the tag(s)`_ to all executed test cases.
2122
-t, --test <name> `Selects the test cases by name`_.
23+
--task <name> Alias for :option:`--test` that can be used when `executing tasks`_.
2224
-s, --suite <name> `Selects the test suites`_ by name.
2325
-R, --rerunfailed <file> `Selects failed tests`_ from an earlier `output file`_
2426
to be re-executed.
@@ -90,12 +92,14 @@ Command line options for test execution
9092
Command line options for post-processing outputs
9193
------------------------------------------------
9294

95+
--rpa Turn on `generic automation`_ mode.
9396
-R, --merge Changes result combining behavior to `merging <merging outputs_>`__.
9497
-N, --name <name> `Sets the name`_ of the top level test suite.
9598
-D, --doc <document> `Sets the documentation`_ of the top-level test suite.
9699
-M, --metadata <name:value> `Sets free metadata`_ for the top-level test suite.
97100
-G, --settag <tag> `Sets the tag(s)`_ to all processed test cases.
98101
-t, --test <name> `Selects the test cases by name`_.
102+
--task <name> Alias for :option:`--test`.
99103
-s, --suite <name> `Selects the test suites`_ by name.
100104
-i, --include <tag> `Selects the test cases`_ by tag.
101105
-e, --exclude <tag> `Selects the test cases`_ by tag.
@@ -143,6 +147,7 @@ Command line options for post-processing outputs
143147
--version Prints the `version information`_.
144148

145149

150+
.. _generic automation: `Task execution`_
146151
.. _Parse only these files: `Selecting files to parse`_
147152
.. _Sets the name: `Setting the name`_
148153
.. _Sets the documentation: `Setting the documentation`_

‎doc/userguide/src/CreatingTestData/CreatingTasks.rst

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
Creating tasks
2+
==============
3+
4+
In addition to test automation, Robot Framework can be used for other
5+
automation purposes, including `robotic process automation`__ (RPA).
6+
It has been always been possible, bu Robot Framework 3.1 added official
7+
support for automating *tasks*, not only tests. For most parts creating
8+
tasks works the same way as `creating tests`_ and the only real difference
9+
is in terminology. Tasks can also be organized into suites__ exactly like
10+
test cases.
11+
12+
__ https://en.wikipedia.org/wiki/Robotic_process_automation
13+
__ `Creating test suites`_
14+
15+
.. contents::
16+
:depth: 2
17+
:local:
18+
19+
Task syntax
20+
-----------
21+
22+
Tasks are created based on the available keywords exactly like test cases,
23+
and the task syntax is in general identical to the `test case syntax`_.
24+
The main difference is that tasks are created in task sections (or tables)
25+
instead of test case sections:
26+
27+
.. sourcecode:: robotframework
28+
29+
*** Tasks ***
30+
Process invoice
31+
Read information from PDF
32+
Validate information
33+
Submit information to backend system
34+
Validate information is visible in web UI
35+
36+
It is an error to have both tests and tasks in same file.
37+
38+
Task related settings
39+
---------------------
40+
41+
Settings that can be used in the task section are exactly the same as in
42+
the `test case section`__. In the `setting section`__ it is possible to use
43+
:setting:`Task Setup`, :setting:`Task Teardown`, :setting:`Task Template`
44+
and :setting:`Task Timeout` instead of their :setting:`Test` variants.
45+
46+
__ `Settings in the Test Case table`_
47+
__ `Test case related settings in the Setting table`_

‎doc/userguide/src/CreatingTestData/CreatingTestCases.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,17 @@
1+
.. _Creating tests:
2+
13
Creating test cases
24
===================
35

46
This section describes the overall test case syntax. Organizing test
57
cases into `test suites`_ using `test case files`_ and `test suite
68
directories`_ is discussed in the next section.
79

10+
When using Robot Framework for other automation purposes than test
11+
automation, it is recommended to create *tasks* instead of tests.
12+
The task syntax is for most parts identical to the test syntax,
13+
and the differences are explained in the `Creating tasks`_ section.
14+
815
.. contents::
916
:depth: 2
1017
:local:

‎doc/userguide/src/CreatingTestData/CreatingTestSuites.rst

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
Creating test suites
22
====================
33

4-
Robot Framework test cases are created in test case files, which can
4+
Robot Framework `test cases`__ are created in test case files, which can
55
be organized into directories. These files and directories create a
6-
hierarchical test suite structure.
6+
hierarchical test suite structure. Same concepts apply also when
7+
`creating tasks`_, but the terminology differs.
8+
9+
__ `Creating test cases`_
710

811
.. contents::
912
:depth: 2
@@ -41,7 +44,7 @@ test suite:
4144
now deprecated and only the format above, case-insensitively, is
4245
supported.
4346

44-
__ `Test case syntax`_
47+
__ `Creating test cases`_
4548

4649
Test suite directories
4750
----------------------
@@ -102,6 +105,10 @@ initialization files is explained below.
102105
Notice that keywords used as setups and teardowns must be available in
103106
test case files where tests using them are. Defining keywords in the
104107
initialization file itself is not enough.
108+
`Task Setup`:setting:, `Task Teardown`:setting:, `Task Timeout`:setting:
109+
Aliases for `Test Setup`:setting:, `Test Teardown`:setting:,
110+
and `Test Timeout`:setting:, respectively, that can be used when
111+
`creating tasks`_, not tests.
105112
`Default Tags`:setting:, `Test Template`:setting:
106113
Not supported in initialization files.
107114

‎doc/userguide/src/CreatingTestData/TestDataSyntax.rst

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
Test data syntax
22
================
33

4-
This section covers Robot Framework's overall test data
5-
syntax. The following sections will explain how to actually create test
6-
cases, test suites and so on.
4+
This section covers Robot Framework's overall test data syntax. The following
5+
sections will explain how to actually create test cases, test suites and so on.
6+
Although this section mostly uses term *test*, the same rules apply also
7+
when `creating tasks`_.
78

89
.. contents::
910
:depth: 2
@@ -42,10 +43,10 @@ often Python.
4243
Test data sections
4344
------------------
4445

45-
Robot Framework test data is defined in different sections, often also
46+
Robot Framework data is defined in different sections, often also
4647
called tables, listed below:
4748

48-
.. table:: Different test data sections
49+
.. table:: Different sections in data
4950
:class: tabular
5051

5152
+------------+--------------------------------------------+
@@ -62,6 +63,10 @@ called tables, listed below:
6263
| Test Cases | `Creating test cases`_ from available |
6364
| | keywords. |
6465
+------------+--------------------------------------------+
66+
| Tasks | `Creating tasks`_ using available |
67+
| | keywords. Single file can only contain |
68+
| | either test cases or tasks. |
69+
+------------+--------------------------------------------+
6570
| Keywords | `Creating user keywords`_ from existing |
6671
| | lower-level keywords |
6772
+------------+--------------------------------------------+

‎doc/userguide/src/ExecutingTestCases/ConfiguringExecution.rst

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,8 +45,8 @@ Selecting test cases
4545
--------------------
4646

4747
Robot Framework offers several command line options for selecting
48-
which test cases to execute. The same options also work when
49-
post-processing outputs with Rebot_.
48+
which test cases to execute. The same options work also when `executing
49+
tasks`_ and when post-processing outputs with Rebot_.
5050

5151
By test suite and test case names
5252
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -88,6 +88,9 @@ automatically. The :option:`--suite` option can be useful in that
8888
case, but in general, selecting test cases by tag names is more
8989
flexible.
9090

91+
When `executing tasks`_, it is possible to use the :option:`--task` option
92+
as an alias for :option:`--test`.
93+
9194
By tag names
9295
~~~~~~~~~~~~
9396

‎doc/userguide/src/ExecutingTestCases/PostProcessing.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,22 @@ Return codes from Rebot are exactly same as when `running tests`__.
5656

5757
__ `Return codes`_
5858

59+
Controlling execution mode
60+
~~~~~~~~~~~~~~~~~~~~~~~~~~
61+
62+
Rebot notices have tests__ or tasks__ been run, and by default preserves the
63+
execution mode. The mode affects logs and reports so that in the former case
64+
they will use term *test* like `Test Log` and `Test Statistics`, and in
65+
the latter case term *task* like `Task Log` and `Task Statistics`.
66+
67+
Rebot also supports using :option:`--rpa` or :option:`--norpa` options to set
68+
the execution mode explicitly. This is necessary if multiple output files
69+
are processed and they have conflicting modes.
70+
71+
__ `Test execution`_
72+
__ `Task execution`_
73+
74+
5975
Creating different reports and logs
6076
-----------------------------------
6177

‎doc/userguide/src/ExecutingTestCases/TaskExecution.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. _executing tasks:
2+
3+
Task execution
4+
==============
5+
6+
Robot Framework can be used also for other automation purposes than test
7+
automation, and starting from Robot Framework 3.1 it is possible to
8+
explicitly create__ and execute tasks. For most parts task execution
9+
and test execution work the same way, and this section explains the
10+
differences.
11+
12+
__ `Creating tasks`_
13+
14+
.. contents::
15+
:depth: 2
16+
:local:
17+
18+
Generic automation mode
19+
-----------------------
20+
21+
When Robot Framework is used execute a file and it notices that the file
22+
has tasks, not tests, it automatically sets itself into the generic automation
23+
mode. This mode does not change the actual execution at all, but when
24+
logs and reports are created, they use term *task*, not *test*. They have,
25+
for example, headers like `Task Log` and `Task Statistics` instead of
26+
`Test Log` and `Test Statistics`.
27+
28+
The generic automation mode can also be enabled by using the :option:`--rpa`
29+
option. In that case the executed files can have either tests or tasks.
30+
Alternatively :option:`--norpa` can be used to force the test automation
31+
mode even if executed files contain tasks. If neither of these options are
32+
used, it is an error to execute multiple files so that some have tests and
33+
others have tasks.
34+
35+
The executio 10000 n mode is stored in the generated `output file`_ and read by
36+
Rebot_ if outputs are post-processed. The mode can also `be set when
37+
using Rebot`__ if necessary.
38+
39+
__ `Controlling execution mode`_
40+
41+
Task related command line options
42+
---------------------------------
43+
44+
All normal command line options can be used when executing tasks. If there
45+
is a need to `select only certain tasks for execution`__, :option:`--task`
46+
can be used instead of :option:`--test`. Additionally the aforementioned
47+
:option:`--rpa` can be used to control the execution mode.
48+
49+
__ `Selecting test cases`__

‎doc/userguide/src/GettingStarted/Introduction.rst

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,26 @@
11
Introduction
22
============
33

4-
Robot Framework is a Python-based, extensible keyword-driven test
5-
automation framework for end-to-end acceptance testing and
6-
acceptance-test-driven development (ATDD). It can be used for testing
7-
distributed, heterogeneous applications, where verification requires
8-
touching several technologies and interfaces.
4+
Robot Framework is a Python-based, extensible keyword-driven automation
5+
framework for acceptance testing, acceptance test driven development (ATDD),
6+
behavior driven development (BDD) and robotic process automation (RPA). It
7+
can be used in distributed, heterogeneous environments, where automation
8+
requires using different technologies and interfaces.
99

1010
The framework has a rich ecosystem around it consisting of various generic
11-
test libraries and tools that are developed as separate projects. For more
11+
libraries and tools that are developed as separate projects. For more
1212
information about Robot Framework and the ecosystem, see
1313
http://robotframework.org.
1414

1515
Robot Framework is open source software released under the `Apache License
1616
2.0`_. Its development is sponsored by the `Robot Framework Foundation
1717
<http://robotframework.org/foundation>`_.
1818

19+
.. note:: The official RRA support was added in Robot Framework 3.1.
20+
This User Guide still talks mainly about creating tests, test data,
21+
and test libraries, but same concepts apply also when `creating
22+
tasks`_.
23+
1924
.. contents::
2025
:depth: 2
2126
:local:
@@ -78,10 +83,10 @@ diagram below.
7883
Robot Framework architecture
7984

8085
The `test data`_ is in simple, easy-to-edit tabular format. When
81-
Robot Framework is started, it processes the test data, `executes test
86+
Robot Framework is started, it processes the data, `executes test
8287
cases`__ and generates logs and reports. The core framework does not
8388
know anything about the target under test, and the interaction with it
84-
is handled by `test libraries`__. Libraries can either use application
89+
is handled by libraries__. Libraries can either use application
8590
interfaces directly or use lower level test tools as drivers.
8691

8792
__ `Executing test cases`_

‎doc/userguide/src/RobotFrameworkUserGuide.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@
4444

4545
.. include:: CreatingTestData/TestDataSyntax.rst
4646
.. include:: CreatingTestData/CreatingTestCases.rst
47+
.. include:: CreatingTestData/CreatingTasks.rst
4748
.. include:: CreatingTestData/CreatingTestSuites.rst
4849
.. include:: CreatingTestData/UsingTestLibraries.rst
4950
.. include:: CreatingTestData/Variables.rst
@@ -61,6 +62,7 @@
6162

6263
.. include:: ExecutingTestCases/BasicUsage.rst
6364
.. include:: ExecutingTestCases/TestExecution.rst
65+
.. include:: ExecutingTestCases/TaskExecution.rst
6466
.. include:: ExecutingTestCases/PostProcessing.rst
6567
.. include:: ExecutingTestCases/ConfiguringExecution.rst
6668
.. include:: ExecutingTestCases/OutputFiles.rst

0 commit comments

Comments
 (0)
0