4 new revisions:
Revision: 57366144e4ac
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 08:02:13 2013
Log: apidocs: Enhanced TestSuite.run and related docs in
robot.running....
http://code.google.com/p/robotframework/source/detail?r=57366144e4ac
Revision: 74b3b4926b7c
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 08:31:50 2013
Log: apidocs: some enhancements to the front page
http://code.google.com/p/robotframework/source/detail?r=74b3b4926b7c
Revision: 4a4b719a3dd7
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 10:22:16 2013
Log: apidocs enhancements....
http://code.google.com/p/robotframework/source/detail?r=4a4b719a3dd7
Revision: ea167936e4c8
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 10:22:20 2013
Log: Automated merge with https://code.google.com/p/robotframework/
http://code.google.com/p/robotframework/source/detail?r=ea167936e4c8
==============================================================================
Revision: 57366144e4ac
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 08:02:13 2013
Log: apidocs: Enhanced TestSuite.run and related docs in robot.running.
Update issue 1468
TestSuite.run looks pretty good now!
http://code.google.com/p/robotframework/source/detail?r=57366144e4ac
Modified:
/src/robot/running/__init__.py
/src/robot/running/model.py
=======================================
--- /src/robot/running/__init__.py Fri Jun 7 17:36:56 2013
+++ /src/robot/running/__init__.py Mon Jun 10 08:02:13 2013
@@ -69,7 +69,8 @@
that the suite created based on the file could be edited further using
the same API.
-Now that we have a test suite ready, let's run it and verify that the
returned
+Now that we have a test suite ready, let's
+:meth:`run <robot.running.model.TestSuite.run>` it and verify that the
returned
:class:`~robot.result.executionresult.Result` object contains correct
information::
=======================================
--- /src/robot/running/model.py Mon Jun 10 04:05:07 2013
+++ /src/robot/running/model.py Mon Jun 10 08:02:13 2013
@@ -151,63 +151,47 @@
self.visit(Randomizer(suites, tests))
def run(self, settings=None, **options):
- """
- Executes the tests based based the given ``settings`` or
``options``.
+ """Executes the suite based based the given ``settings`` or
``options``.
:param settings: :class:`~robot.conf.settings.RobotSettings` object
to configure test execution.
:param options: Used to construct new
:class:`~robot.conf.settings.RobotSettings` object if
``settings``
are not given.
+ :return: :class:`~robot.result.executionresult.Result` object with
+ information about executed suites and tests.
- Options are given as keyword arguments and their names are same as
- long command line options except without hyphens.
-
- The effective options are all that relate to the actual
- execution of tests. This means, that filtering and writing log,
- report or XUnit is not affected by the given options.
-
- Example::
-
- suite = TestSuite(...)
- ...
- result = suite.run(
- skipteardownonexit=True,
- randomize_suites=True,
- output='my_output.xml'
- )
-
+ If ``options`` are used, their names are the same as long command
line
+ options except without hyphens, and they also have the same
semantics.
Options that can be given on the command line multiple times can be
- passed as lists like `include=['tag1', 'tag2']`.
+ passed as lists like ``variable=['VAR1:value1', 'VAR2:value2']``.
+ If such an option is used only once, it can be given also as a
single
+ string like ``variable='VAR:value'``.
- Example::
-
- suite = TestSuite(...)
- ...
- result = suite.run(include=['tag1, 'tag2'])
-
- If such option is used only once, it can be given also as
- a single string like `include='tag'`.
+ Only options related to the actual test execution have an effect.
+ For example, options related to selecting test cases or creating
+ logs and reports are silently ignored. The output XML generated
+ as part of the execution can be configured, though, including
+ disabling it with ``output=None``.
Example::
- suite = TestSuite(...)
- ...
- result = suite.run(include='tag')
-
- To capture stdout and/or stderr streams, pass open file objects in
as
- special keyword arguments `stdout` and `stderr`, respectively.
-
- Example::
+ result = suite.run(variable='EXAMPLE:value',
+ critical='regression',
+ output='example.xml',
+ exitonfailure=True,
+ skipteardownonexit=True)
+ print result.return_code
- suite = TestSuite(...)
- ...
- stdout_file = open('test_output.txt', 'w')
- stderr_file = open('test_errors.txt', 'w')
- result = suite.run(stdout=stdout_file, stderr=stderr_file)
+ To save memory, the returned
+ :class:`~robot.result.executionresult.Result` object object does
not
+ have any information about the executed keywords. If that
information
+ is needed, the created output XML file needs to be read using the
+ :class:`~robot.result.resultbuilder.ExecutionResult` factory
method.
- Please see examples at :mod:`running API <robot.running>`
- on how to create runnable test suites.
+ See the :mod:`package level <robot.running>` documentation for
+ more examples, including how to construct executable test suites
and
+ how to create logs and reports based on the execution results.
"""
STOP_SIGNAL_MONITOR.start()
IMPORTER.reset()
==============================================================================
Revision: 74b3b4926b7c
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 08:31:50 2013
Log: apidocs: some enhancements to the front page
http://code.google.com/p/robotframework/source/detail?r=74b3b4926b7c
Modified:
/doc/api/index.rst
=======================================
--- /doc/api/index.rst Thu May 10 03:53:30 2012
+++ /doc/api/index.rst Mon Jun 10 08:31:50 2013
@@ -2,23 +2,24 @@
Robot Framework API documentation
=================================
+This documentation describes the public API of `Robot Framework`__.
+Installation, basic usage and wealth of other topics are
+covered by the `Robot Framework User Guide`__.
-This document describes the public API of Robot Framework. Installation,
-basic usage and wealth of other topics are covered in `Robot Framework
User Guide`__.
-
-Main API entry points are documented here, but the lower level
implementation
-details are not that well documented. If the documentation is insufficient,
-it is possible to view the source code by clicking `[source]` link in the
-documentation. In case viewing the source is not helpful either,
-questions may be sent to the `users mailing list`__.
+Main API entry points are documented here, but the lower level
+implementation details are not always that well documented. If the
+documentation is insufficient, it is possible to view the source code
+by clicking `[source]` link in the documentation. In case viewing the
+source is not helpful either, questions may be sent to the
+`robotframework-users`__ mailing list.
+__ http://robotframework.org
__ http://code.google.com/p/robotframework/wiki/UserGuide
__ http://groups.google.com/group/robotframework-users
.. toctree::
:maxdepth: 2
-
Entry points
============
@@ -31,10 +32,9 @@
* :py:mod:`robot.testdoc` entry point for the `testdoc`__ tool.
* :py:mod:`robot.tidy` entry point for the `tidy`__ tool.
-__ http://code.google.com/p/robotframework/wiki/LibraryDocumentationTool
-__ http://code.google.com/p/robotframework/wiki/TestDataDocumentationTool
-__ http://code.google.com/p/robotframework/wiki/TestDataTidyingTool
-
+__
http://robotframework.googlecode.com/hg/doc/userguide/RobotFrameworkUserGuide.html#libdoc
+__
http://robotframework.googlecode.com/hg/doc/userguide/RobotFrameworkUserGuide.html#testdoc
+__
http://robotframework.googlecode.com/hg/doc/userguide/RobotFrameworkUserGuide.html#tidy
Java entry points
=================
@@ -49,7 +49,6 @@
.. automodule:: robot.api
-
All packages
============
@@ -62,7 +61,6 @@
autodoc/robot
autodoc/robot.api
- autodoc/robot.common
autodoc/robot.conf
autodoc/robot.htmldata
autodoc/robot.libdocpkg
@@ -77,8 +75,6 @@
autodoc/robot.variables
autodoc/robot.writer
-
-
Indices
=======
==============================================================================
Revision: 4a4b719a3dd7
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 10:22:16 2013
Log: apidocs enhancements.
Update issue 1468
Further enhancements to model objects, especially on the result side.
http://code.google.com/p/robotframework/source/detail?r=4a4b719a3dd7
Modified:
/src/robot/model/testsuite.py
/src/robot/model/totalstatistics.py
/src/robot/result/configurer.py
/src/robot/result/keywordremover.py
/src/robot/result/testsuite.py
=======================================
--- /src/robot/model/testsuite.py Thu Jun 6 13:28:21 2013
+++ /src/robot/model/testsuite.py Mon Jun 10 10:22:16 2013
@@ -56,6 +56,7 @@
@setter
def metadata(self, metadata):
+ """Free test suite metadata as a dictionary."""
return Metadata(metadata)
@setter
@@ -72,21 +73,38 @@
@property
def id(self):
+ """An automatically generated unique id.
+
+ The root suite has id ``s1``, its children have ids ``s1-s1``,
+ ``s1-s2``, ..., their children get ids ``s1-s1-s1``, ``s1-s1-s2``,
+ ..., ``s1-s2-s1``, ..., and so on.
+ """
if not self.parent:
return 's1'
return '%s-s%d' % (self.parent.id,
self.parent.suites.index(self)+1)
@property
def longname(self):
+ """Suite name prefixed with all parent suite names."""
if not self.parent:
return self.name
return '%s.%s' % (self.parent.longname, self.name)
@property
def test_count(self):
+ """Number of the tests in this suite, recursively."""
return len(self.tests) + sum(suite.test_count for suite in
self.suites)
def set_tags(self, add=None, remove=None, persist=False):
+ """Add and/or remove specified tags to the tests in this suite.
+
+ :param add: Tags to add as a list or, if adding only one,
+ as a single string.
+ :param remove: Tags to remove as a list or as a single string.
+ Can be given as patterns where ``*`` and ``?`` work as
wildcards.
+ :param persist: Add/remove specified tags also to new tests added
+ to this suite in the future.
+ """
setter = TagSetter(add, remove)
self.visit(setter)
if persist:
@@ -94,6 +112,21 @@
def filter(self, included_suites=None, included_tests=None,
included_tags=None, excluded_tags=None):
+ """Select test cases and remove others from this suite.
+
+ Parameters have the same semantics as ``--suite``, ``--test``,
+ ``--include``, and ``--exclude`` command line options. All of them
+ can be given as a list of strings, or when selecting only one, as
+ a single string.
+
+ Child suites that contain no tests after filtering are
automatically
+ removed.
+
+ Example::
+
+ suite.filter(included_tests=['Test 1', '* Example'],
+ included_tags='priority-1')
+ """
self.visit(Filter(included_suites, included_tests,
included_tags, excluded_tags))
@@ -101,6 +134,7 @@
self.visit(SuiteConfigurer(**options))
def remove_empty_suites(self):
+ """Removes all child suites not containing any tests,
recursively."""
self.visit(EmptySuiteRemover())
def visit(self, visitor):
=======================================
--- /src/robot/model/totalstatistics.py Mon Jun 10 07:17:04 2013
+++ /src/robot/model/totalstatistics.py Mon Jun 10 10:22:16 2013
@@ -22,7 +22,7 @@
:ivar critical: Instance of :class:`~robot.model.stats.TotalStat` for
critical tests.
:ivar all: Instance of :class:`~robot.model.stats.TotalStat` for
- all the tests, including critical.
+ all the tests.
"""
def __init__(self):
@@ -37,8 +37,9 @@
@property
def message(self):
- """Returns a summary of total statistics in a string
representation,
- for example::
+ """String representation of the statistics.
+
+ For example::
2 critical tests, 1 passed, 1 failed
2 tests total, 1 passed, 1 failed
=======================================
--- /src/robot/result/configurer.py Thu Jun 6 13:13:01 2013
+++ /src/robot/result/configurer.py Mon Jun 10 10:22:16 2013
@@ -17,6 +17,18 @@
class SuiteConfigurer(model.SuiteConfigurer):
+ """Result suite configured.
+
+ Calls suite's
+ :meth:`~robot.result.testsuite.TestSuite.remove_keywords`,
+ :meth:`~robot.result.testsuite.TestSuite.filter_messages` and
+ :meth:`~robot.result.testsuite.TestSuite.set_criticality` methods
+ and sets it's start and end time based on the given named parameters.
+
+ ``base_config`` is forwarded to
+ :class:`robot.model.SuiteConfigurer
<robot.model.configurer.SuiteConfigurer>`
+ that will do further configuration based on them.
+ """
def __init__(self, remove_keywords=None, log_level=None,
start_time=None,
end_time=None, critical_tags=None, non_critical_tags=None,
=======================================
--- /src/robot/result/keywordremover.py Sat Jun 8 02:14:24 2013
+++ /src/robot/result/keywordremover.py Mon Jun 10 10:22:16 2013
@@ -18,15 +18,6 @@
def KeywordRemover(how):
- """Returns correct keyword remover based on given criteria.
-
- `how` is a string of one of the following:
- * `PASSED` returns :class:`.PassedKeywordRemover`.
- * `FOR` returns :class:`ForLoopItemsRemover`.
- * `ALL` returns :class:`AllKeywordsRemover`.
- * `WUKS` return :class:`WaitUntilKeywordSucceedsRemover`.
- * Otherwise, :class:`~robot.model.visitor.SkipAllVisitor` is
returned.
- """
return {
'PASSED': PassedKeywordRemover,
'FOR': ForLoopItemsRemover,
@@ -56,13 +47,13 @@
class AllKeywordsRemover(_KeywordRemover):
- """Removes all keywords."""
+
def visit_keyword(self, keyword):
self._clear_content(keyword)
class PassedKeywordRemover(_KeywordRemover):
- """Removes those keywords that have passed."""
+
def start_suite(self, suite):
if not suite.statistics.all.failed:
for keyword in suite.keywords:
@@ -79,7 +70,6 @@
class ForLoopItemsRemover(_KeywordRemover):
- """Removes for loop keywords."""
_message = '%d passing step%s removed using --RemoveKeywords option.'
def start_keyword(self, kw):
@@ -94,7 +84,6 @@
class WaitUntilKeywordSucceedsRemover(_KeywordRemover):
- """Removes `BuiltIn.Wait Until Keyword Succeeds` keywords."""
_message = '%d failing step%s removed using --RemoveKeywords option.'
def start_keyword(self, kw):
@@ -106,7 +95,7 @@
def _remove_keywords(self, keywords):
include_from_end = 2 if keywords[-1].passed else 1
return self._kws_with_warnings(keywords[:-include_from_end]) \
- + keywords[-include_from_end:]
+ + keywords[-include_from_end:]
def _kws_with_warnings(self, keywords):
return [kw for kw in keywords if self._contains_warning(kw)]
=======================================
--- /src/robot/result/testsuite.py Sat Jun 8 02:14:24 2013
+++ /src/robot/result/testsuite.py Mon Jun 10 10:22:16 2013
@@ -39,53 +39,57 @@
:ivar name: Test suite name.
:ivar doc: Test suite documentation.
:ivar metadata: Test suite metadata as a dictionary.
- :ivar source: Path to the source file.
+ :ivar source: Path to the source file or directory.
:ivar suites: A list of child :class:`~.testsuite.TestSuite`
instances.
:ivar tests: A list of :class:`~.testcase.TestCase` instances.
:ivar keywords: A list containing setup and teardown
:class:`~.keyword.Keyword` instances.
- :ivar starttime: Test suite execution start time as a timestamp.
- :ivar endtime: Test suite execution end time as a timestamp.
"""
model.TestSuite.__init__(self, name, doc, metadata, source)
- self.message = message
+ self.message = message #: Suite setup/teardown error message.
self.starttime = starttime
self.endtime = endtime
self._criticality = None
@property
def passed(self):
- """Returns boolean based on if any critical test cases failed in
the
- suite."""
+ """``True`` if all critical tests succeeded, ``False``
otherwise."""
return not self.statistics.critical.failed
@property
def status(self):
- """Returns string `'PASS'` or `'FAIL'` if the test suite failed."""
+ """``'PASS'`` if all critical tests succeeded, ``'FAIL'``
otherwise."""
return 'PASS' if self.passed else 'FAIL'
@property
def statistics(self):
- """Builds a
new :class:`~robot.model.totalstatistics.TotalStatistics`
- object based from itself and returns it."""
+ """Suite statistics as
a :class:`~robot.model.totalstatistics.TotalStatistics` object.
+
+ Recreated every time this property is accessed, so saving the
results
+ to a variable and inspecting it is often a good idea::
+
+ stats = suite.statistics
+ print stats.critical.failed
+ print stats.all.total
+ print stats.message
+ """
return TotalStatisticsBuilder(self).stats
@property
def full_message(self):
- """Returns a possible failure message."""
+ """Combination of :attr:`message` and :attr:`stat_message`."""
if not self.message:
return self.stat_message
return '%s\n\n%s' % (self.message, self.stat_message)
@property
def stat_message(self):
- """Returns a string with passed and failed information of critical
as
- well as all test cases."""
+ """String representation of suite's :attr:`statistics`."""
return self.statistics.message
@property
def elapsedtime(self):
- """Returns total execution time of the suite in milliseconds."""
+ """Total execution time of the suite in milliseconds."""
if self.starttime and self.endtime:
return utils.get_elapsed_time(self.starttime, self.endtime)
return sum(child.elapsedtime for child in
@@ -93,7 +97,10 @@
@property
def criticality(self):
- """Returns if the test suite is critical or not."""
+ """Used by tests to determine are they considered critical or not.
+
+ Set using :meth:`set_criticality`.
+ """
if self.parent:
return self.parent.criticality
if self._criticality is None:
@@ -101,33 +108,50 @@
return self._criticality
def set_criticality(self, critical_tags=None, non_critical_tags=None):
- """Set which tags are considered critical for the test suite and
which
- are not."""
+ """Sets which tags are considered critical and which non-critical.
+
+ Tags can be given as lists of strings or, when giving only one,
+ as single strings. This information is used by tests to determine
+ are they considered critical or not.
+
+ Criticality can be set only to the top level test suite.
+ """
if self.parent:
raise TypeError('Criticality can only be set to top level
suite')
self._criticality = Criticality(critical_tags, non_critical_tags)
def remove_keywords(self, how):
- """Remove keywords based on
- :func:`given
criteria<robot.result.keywordremover.KeywordRemover>`."""
+ """Remove keywords based on the given condition.
+
+ ``how`` is either ``ALL``, ``PASSED``, ``FOR``, or ``WUKS``.
+ These values have exact same semantics as values accepted by
+ ``--removekeywords`` command line option.
+ """
self.visit(KeywordRemover(how))
def filter_messages(self, log_level='TRACE'):
- """Visitor to filter :class:`~.keyword.Keyword` messages of a given
- log level.
-
- :attr log_level: Optional log level. If no log level is given,
messages
- are filtered on the `TRACE` log level.
- """
+ """Remove log messages below the specified ``log_level``."""
self.visit(MessageFilter(log_level))
def configure(self, **options):
- """Configure suite with
- :class:`set of options <.configurer.SuiteConfigurer>`."""
+ """A shortcut to configure a suite using one method call.
+
+ ``options`` are passed to
+ :class:`~robot.result.configurer.SuiteConfigurer` that will then
call
+ :meth:`filter`, :meth:`remove_keywords`, etc. based on them.
+
+ Example::
+
+ suite.configure(remove_keywords='PASSED',
+ critical_tags='smoke',
+ doc='Smoke test results.')
+ """
self.visit(SuiteConfigurer(**options))
def handle_suite_teardown_failures(self):
+ """Internal usage only."""
self.visit(SuiteTeardownFailureHandler())
def suite_teardown_failed(self, message):
+ """Internal usage only."""
self.visit(SuiteTeardownFailed(message))
==============================================================================
Revision: ea167936e4c8
Branch: default
Author: Pekka Klärck
Date: Mon Jun 10 10:22:20 2013
Log: Automated merge with https://code.google.com/p/robotframework/
http://code.google.com/p/robotframework/source/detail?r=ea167936e4c8
--
---
You received this message because you are subscribed to the Google Groups "robotframework-commit" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to robotframework-commit+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
