El 13/05/10 18:41, Cleto Martin Angelina escribió:
tags 581178 - patch
thanks
Oops, it seems I misclicked the wrong file, sorry! I'm sending the correct
one now.
I'm sorried, Ignacio but the patch you have sent is invalid. Please,
generate a correct one. When you have a tested patch, I'll mark this
bug with de patch flag. Meanwhile, i'm going to delete the patch flag.
Regards,
Cleto.
Ok, I have re-done the patch. I have been a mess with this issue, but I
hope this is the good one.
HTH
Nacho
--- atheist-0.20100416/doc/intro.rst 2010-05-05 17:03:30.000000000 +0200
+++ atheist-0.20100416-nacho/doc/intro.rst 2010-05-14 19:55:14.000000000 +0200
@@ -4,7 +4,7 @@
Atheist is a simple framework for running test cases. You write small
files in Python language using a set of predefined functions and
classes. In many senses, the concept is quite similar to *make* or the
-SCons framework although Atheist isn't a building system at all.
+SCons framework although Atheist is not a building system at all.
Features:
@@ -12,7 +12,7 @@
<http://en.wikipedia.org/wiki/Black-box_testing>`_: system and
acceptance tests. It may execute any kind of external shell program.
* `White-box testing
- <http://en.wikipedia.org/wiki/White-box_testing>`_ by means `unitest
+ <http://en.wikipedia.org/wiki/White-box_testing>`_ by means of `unitest
<http://docs.python.org/library/unittest.html`_ and standard
Python functions.
* `Python doctests <http://en.wikipedia.org/wiki/Doctest>`_.
@@ -23,12 +23,12 @@
ToDo:
-* Plugins per project.
+* Per-project plugins.
* Limit/perf testing.
-* Remote tests.
+* Remote testing.
* Test deployment.
* Remote management.
-* Distributed tests.
+* Distributed testing.
Test objects
@@ -36,12 +36,12 @@
The Test object is the minimal testing unit. Each Test instance
defines an individual execution (a shell command) that may be
-checked for its success termination. The Test constructor accepts many
-parameters that may change the test exception behavior in several
-ways. The only mandatory parameter is ``cmd`` that is the command to
-exec.
+checked for success upon termination. The Test constructor accepts many
+parameters that may change the test's exception behavior in several
+ways. The only mandatory parameter is ``cmd`` which is the command to
+execute.
-The Test object is responsible to execute the command and check its
+The Test object is responsible for executing the command and checking its
termination value. A very basic example::
Test('true')
@@ -50,9 +50,9 @@
Test files
----------
-The Test instances need to be defined into text source files (with
-extension ``.test``). Although these files are written in a subset of
-Python language, they may be seen as declarative programs. You tell
+Test instances need to be defined in text source files (with
+``.test`` extension). Although these files are written in a subset of
+the Python language, they may be seen as declarative programs. You tell
Atheist what you want to test and even the order, but the decision
about when to run the corresponding action is taken by Atheist; some
of them may be never done.
@@ -70,7 +70,7 @@
^^^^^^^^
Any Test constructor accepts the next key-val parameters. All of them
-are optional. Beside the parameter name appears its type and
+are optional. Beside the parameter's name appear its type and
default value.
**check** -- type: ``bool``, default: ``True``
@@ -84,7 +84,7 @@
**delay** -- type: ``int``, default: ``0``
- Waits for 'delay' seconds before launch the task actions.
+ Waits for 'delay' seconds before launching the task actions.
**desc** -- type: ``str``
@@ -92,9 +92,9 @@
**detach** -- type: ``bool``, default: ``False``
- When ``detach`` is ``False`` the next task does not starts until
+ When ``detach`` is ``False`` the next task does not start until
the current one ends. When ``detach`` is ``True`` the next task is
- executed even the current one is running.
+ executed even if the current one is still running.
**env** -- type: ``str``:``str`` map
@@ -102,24 +102,24 @@
**expected** -- type: int
- Expected program return code. It may be negative if the process is
+ Expected return code for the command. It may be negative if the process is
killed by a signal.
**tid** -- type: ``str``
It is a unique string Task IDentifier. You can get a reference to
- the task later giving this value to the :func:`get_task` function.
+ the task later by giving this value to the :func:`get_task` function.
**must_fail** -- type: ``bool``, default: ``False``
- When you expect the program terminates with error but the
- return code is not known (i.e: is different that zero). You should
+ When you expect the program to end with an error but the
+ return code is not known (i.e: is different from zero). You should
check other conditions (stdout, stderr, generated files, etc) to differentiate
alternative fails.
**parent** -- type: CompositeTask
- Use this to aggregate current test in a already defined CompositeTask.
+ Use this to aggregate the current test to an already defined CompositeTask.
**template** -- type: Template list
@@ -128,17 +128,17 @@
**timeout** -- type: int, default: ``5``
The maximum task execution time (in seconds). When the timeout
- finish, Atheist sends the programmed signal to the process. To
+ finishes, Atheist sends the programmed signal to the process. To
avoid timed termination (daemonic task) give ``timeout=0``.
**save_stderr** -- type: ``bool``, default: ``False``
- Store the process stderr in an actual file. If the ``stderr``
+ Store the process' stderr in a text file. If the ``stderr``
parameter is not set, Atheist will create an unique name for the file.
**save_stdout** -- type: ``bool``, default: ``False``
- Store the process stdout in an actual file. If the ``stdout``
+ Store the process' stdout in a text file. If the ``stdout``
parameter is not set, Atheist will create an unique name for the file.
**shell** -- type: ``bool``, default: ``False``
@@ -148,17 +148,17 @@
**signal** -- type: int, default: SIGKILL
It is the signal that Atheist sends to the process when the
- ``timeout`` finish.
+ ``timeout`` finishes.
**stdout** -- type: ``str``
- Is the file name to save the process stdout. Setting this
+ It is the name of the file where to save the process' stdout. Setting this
parameters implies save_stdout = True.
**todo** -- type: ``bool``, default: ``False``
- It indicates the task is not fully verified and it is possible it
- can fail unduly. This has not effect when the task ends
+ It indicates that the task is not fully verified and it is possible that it
+ fail unduly. This has no effect when the task ends
successfully.
Not all of these key-args are available for all Task classes. See :ref:`task_types`.
@@ -167,13 +167,13 @@
Task results
------------
-The execution of any task return a value:
+The execution of any task returns a value, which can be:
-* **FAIL**: The task ran normally but the user requirements or conditions did not achieved. The test **failed**.
-* **OK**: The task ran successfully and all required conditions and/or return value was right.
+* **FAIL**: The task ran normally but user requirements or conditions were not met. The test **failed**.
+* **OK**: The task ran successfully and all required conditions and/or return values were correct.
* **NOEXEC**: The task was skipped or it was not executed.
-* **ERROR**: The task implementation is wrong and task execution failed itself.
-* **UNKNOWN**: The task was executed but the its result is not known.
+* **ERROR**: The implementation of the task is wrong and the task execution failed itself.
+* **UNKNOWN**: The task was executed but its result is not known.
* **TODO**: The task implementation is unstable and it may produce false failures.
@@ -182,9 +182,9 @@
Templates
---------
-The template is a set of predefined values for the Test
+The template is a set of predefined values for Test
key-values. You may use the same configuration for many tests avoiding
-repeat them. This is an example::
+to repeat them. This is an example::
t1 = Template(timeout=6, expected=-9)
@@ -193,7 +193,7 @@
Both tests will be automatically killed after 6 seconds and the
-expected return value is -9. That means these process receive the
+expected return value is -9. This means that these processes receive the
SIGKILL(9) signal. You may specify several templates as a list.
@@ -201,10 +201,10 @@
Conditions
----------
-The *conditions* are predicates (actually functors) that check for
-specific checks. Conditions may be specified to be checked before
+*Conditions* are predicates (actually, functors) that check for
+specific conditions. Conditions may be specified to be checked before
(pre-conditions) or after (post-conditions) the task execution. If
-any of the condition fails then the task fails. This is an example::
+any of the conditions fail, then the task fails. This is an example::
t = Test('foo')
t.pre += FileExists('/path/to/foofile')
@@ -216,57 +216,57 @@
.. function:: AtheistVersion(version)
- Checks the installed **atheist** version is equal or newer than the
+ Checks that the installed version of **atheist** is equal or newer than the
given number. This is useful to assure recent or experimental features.
.. function:: Callback(*args)
Call the specified function with the given arguments. You must
- avoid the use of this condition as possible.
+ avoid the use of this condition as much as possible.
.. function:: DebPkgInstalled(package)
- Checks the Debian *package* is installed.
+ Checks that Debian package *package* is installed.
.. function:: DirExists(path)
- Checks the directory *path* exists.
+ Checks that directory *path* exists.
.. function:: EnvVarDefined(name[, value])
- Checks the environment variable *name* exists, and optionally has
+ Checks that the environment variable *name* exists, and optionally has
the value *value*.
.. function:: FileExists(filename)
- Checks the directory *filename* exists.
+ Checks that file *filename* exists.
.. function:: FileContains(val[, filename=task.stdout, times=1])
- Checks the file *filename* exists and contains *val*, that may be a
+ Checks that file *filename* exists and contains *val*, which may be a
string or a string list. The file must contain **at least** *times*
- ocurrences of *val*. Default value for *filename* is the stdout of
+ ocurrences of *val*. The default value for *filename* is the stdout of
the corresponding task, and it implies ``save_stdout=True``. This
implies also a FileExists condition for that file.
.. function:: FileEquals(filename1[, filename2=task.stdout])
- Checks the contents of *filename1* and *filename2* are
- identical. Default value for *filename2* is the stdout of the
+ Checks that the contents of *filename1* and *filename2* are
+ identical. The default value for *filename2* is the stdout of the
current task, and it implies ``save_stdout=True``.
.. function:: OpenPort(port[, host='localhost'[, proto='tcp']])
- Checks the *port* is open, that is: a process is listen in it.
+ Checks that port number *port* is open, i.e., a process is listening to it.
.. function:: OutContains(val)
- Checks the task output contains *val*, that may be a string or a
+ Checks that the task's output contains *val*, which may be a string or a
string list.
.. function:: ProcessRunning(pid)
- Checks the given PID belongs to a running process.
+ Checks that the given PID belongs to a running process.
Condition decorators
@@ -284,11 +284,11 @@
.. function:: Poll(condition[, interval=1[, timeout=5]])
- Checks *condition* each *interval* seconds stopping after *timeout*
- seconds or its value become True.
+ Checks *condition* every *interval* seconds, stopping after *timeout*
+ seconds or when its value becomes True.
- In the next example, the task waits for the ``nc`` server become
- ready before continue (a maximum of 5 seconds)::
+ In the next example, the task waits (a maximum of 5 seconds) for the ``nc`` server to become
+ ready before continuing::
t = Test('nc -l -p 2000')
t.post += Poll(OpenPort(2000))
@@ -298,13 +298,13 @@
It is the boolean operator "or".
-Condition decorators may be combined. Next example shows a task that waits
-for a environment variable is removed before execute the command::
+Condition decorators may be combined. The following example shows a task that waits
+for an environment variable to be removed before executing the command::
t = Test('command')
t.pre += Poll(Not(EnvVarDefined('WAIT_FLAG')), timeout=10)
-Note the effect of Poll(Not(condition)) is not the same of Not(Poll(condition)).
+Note that the effect of Poll(Not(condition)) is not the same that Not(Poll(condition)).
.. _task_types:
@@ -313,14 +313,14 @@
------------------------------------
``Task`` is the base class for all executable items. ``Test`` is-a
-``Task`` that run a shell command but other kind of ``Task`` are
+``Task`` that runs a shell command but other kind of ``Task`` are
possible:
**Command**
- It is a non-checked ``Test``. Command is exactly the same than a Test
- with parameter ``check=False``.
+ It is a non-checked ``Test``. Command is exactly the same that a Test
+ with a ``check=False`` parameter.
- The Commands (or other non-checked tests) are not considered in
+ The Commands (or other non-checked Tasks) are not considered in
results counting.
**Daemon**
@@ -332,16 +332,16 @@
* ``check = False``
**UnitTestCase**
- Wrapper to add standard ``unitest.TestCase`` in atheist testcases.
+ Wrapper to add standard ``unitest.TestCase`` to atheist testcases.
**DocTest**
Wrapper to add standard `doctest
- <http://docs.python.org/library/doctest.html>`_ in atheist testcases.
+ <http://docs.python.org/library/doctest.html>`_ to atheist testcases.
**TestFunc**
- Check return value of arbitrary Python functions of methods. Return
- value 0 means success, other case means a code error. For unit
- testing prefer UnitTestCase instead of this.
+ Check the return value of arbitrary Python functions or methods. A return
+ value of 0 means success, otherwise it means a code error. For unit
+ testing, prefer UnitTestCase instead of this.
@@ -352,7 +352,7 @@
It's a special test to kill and **ensure** the termination of other
tasks.
- Next example runs a netcat server during 10 seconds and then kill it::
+ The next example runs a netcat server for 10 seconds and then kills it::
nc = Daemon("nc -l -p 2000")
TaskTerminator(nc, delay=10)
@@ -363,7 +363,7 @@
.. function:: get_task(name)
- Returns the task which ``tid`` attribute is *name*. [include a
+ Returns the task whose ``tid`` attribute is *name*. [include a
sample here]
@@ -371,12 +371,12 @@
Variable substitutions
----------------------
-The testfiles may include some substitutable variable. That is useful
-to locate related files relevant in the test. You must write the
+Test files may include some substitutable variable. This is useful
+to locate test-relevant related files. You must write the
symbol '$' preceding each one of the next words:
**basedir**
- is the name of the directory from atheist was
+ is the name of the directory where atheist was
executed. Usually this is a ``tests`` directory into your project.
**dirname**
@@ -386,10 +386,10 @@
is the path to the testfile without its extension (.test).
**testname**
- is just the name of the testfile, without extension and directory
+ is just the name of the testfile, without extension nor directory
path.
-For example, for next ``vars.test`` file::
+For example, for the following ``vars.test`` file::
Test("echo $basedir $dirname $fname $testname")
@@ -405,25 +405,25 @@
------------------
You may write tasks to execute before and after each test file. To do
-this just put this tasks in files called ``_setup.test`` and
+so, just put these tasks in files called ``_setup.test`` and
``_teardown.test``.
Clean-up
--------
-When your task create files you may track them for automatic
-cleaning. Just add filenames to the task ``gen`` attribute. Here's an
+When your task creates files, you may track them for automatic
+cleaning. Just add their filenames to the task's ``gen`` attribute. Here's an
example::
t = Test('touch foo')
t.gen += 'foo'
-You may specify one o more filenames (a string list).
+You may specify one o more filenames (as a string list).
-If you want the generated files don't be automatically removed for
-manual inspection of results, you must specify the ``--dirty`` option
-(see below). To clean-up these files later, specify ``-C`` option.
+If you want the generated files not to be automatically removed for
+manual inspection of the results, you must specify the ``--dirty`` option
+(see below). To clean-up these files later, specify the ``-C`` option.
Invoking Atheist
@@ -445,7 +445,7 @@
.. cmdoption:: -C, --clean-only
- Don't execute nothing, only remove generated files.
+ Don't execute anything, only remove generated files.
.. cmdoption:: --cols=SCREEN_WIDTH
@@ -453,7 +453,7 @@
.. cmdoption:: -d, --describe
- Describe tasks but does not execute nothing.
+ Describe tasks but don't execute anything.
.. cmdoption:: --dirty
@@ -461,11 +461,11 @@
.. cmdoption:: -e, --stderr
- Print test process stderr.
+ Print the test process' stderr.
.. cmdoption:: -f, --stdout-on-fail
- print task output but only if it fail.
+ Print task output, but only if it fails.
.. cmdoption:: -g, --gen-template
@@ -473,7 +473,7 @@
.. cmdoption:: -i REPORT_DETAIL, --report-detail=REPORT_DETAIL
- Report verbosity (0:nothing, [1:case], 2:task, 3:composite, 4:condition)
+ Verbosity level (0:nothing, [1:case], 2:task, 3:composite, 4:condition)
.. cmdoption:: -j, --skip-setup
@@ -481,7 +481,7 @@
.. cmdoption:: -k, --keep-going
- Continue even with failed tests.
+ Continue despite failed tests.
.. cmdoption:: -l, --list
@@ -505,13 +505,13 @@
.. cmdoption:: -o, --stdout
- Print test process stdout.
+ Print the test process' stdout.
.. cmdoption:: -p PLUGINPATH, --plugin_dir=PLUGINPATH
- Load plugins on that directory (may be given several times).
+ Load plugins fron that directory (may be given several times).
- Print test process stdout.
+ Print the test process' stdout.
.. cmdoption:: -q, --quiet
@@ -527,7 +527,7 @@
.. cmdoption:: -u, --until-failure
- Repeat test until something fails.
+ Repeat tests until something fails.
.. cmdoption:: -v, --verbose
@@ -535,11 +535,11 @@
.. cmdoption:: -w WORKERS, --workers=WORKERS
- Number of simultaneous tasks. Value '0' allows atheist choose number. Default is 1.
+ Number of simultaneous tasks. '0' allows atheist to choose the number. Default is 1.
.. cmdoption:: -x EXT, --extension=EXT
- Extension for the test files.
+ Extension for test files.
@@ -558,14 +558,14 @@
Notifications (other reporters)
===============================
-You may use Atheist to monitor the well working of any application. It
-may send you notifications when some is wrong. The easiest way is to
+You may use Atheist to monitor the proper working of any application. It
+may send you notifications when something is wrong. The easiest way is to
run a testcase with ``cron`` specifying one ``--notify-*`` command-line
-argument. At the moment, two notificators are implemented:
+argument. Currently, two notificators are implemented:
**Email**
The destination is a email account using the SMTP
- protocol. Atheist does not require a SMTP server or smarthost. You
+ protocol. Atheist does not require an SMTP server or smarthost. You
only need to configure an email account that will be used by Atheist
to send mail to any destination. That information must be written in
the ``.atheist`` configuration file. This is an example::
@@ -581,7 +581,7 @@
You must indicate a jabber account that will be used by
Atheist to send notification messages to any other jabber
account. The destination account must accept this contact
- previously. The next is an example for the configuration in the
+ previously. The following is an example for the configuration in the
``.atheist`` file::
[jabber]
___________________________________________________
Enviado a través de http://alumnos.uclm.es/webmail
