Use cases

docs/sphinx/annotated_scenario.yaml

@@ -62,7 +62,7 @@ sequences:
   init:
     # Log-in
     - activity: HTTPRequest
-      url: $(base_url)
+      url: /
       method: OPTIONS
       assert_match_headers: ".*'DAV'.*"
 
@@ -79,15 +79,15 @@ sequences:
   # Other sections can have arbitrary names and are excuted in order of appearance
   main:
     - activity: GetRequest
-      url: $(base_url)/
+      url: /
       assert_match: ".*Index of /.*"
       assert_html:
         "//*[@class='logo']": true
 
     # - activity: $debug()
 
     - activity: PutRequest
-      url: $(base_url)/wsgidav_test_file~$(session_id).txt
+      url: /wsgidav_test_file~$(session_id).txt
       data: "Test"
       assert_max_time: 0.5
       # debug: true
@@ -106,7 +106,7 @@ sequences:
     - activity: $sleep(0.3)
 
     - activity: GetRequest
-      url: $(base_url)/wsgidav_test_file~$(session_id).txt
+      url: /wsgidav_test_file~$(session_id).txt
       assert_match: "Test"
 
     - activity: $sleep(0.3)
@@ -126,4 +126,4 @@ sequences:
     - activity: $sleep(0.1)
 
     - activity: DeleteRequest
-      url: $(base_url)/wsgidav_test_file~$(session_id).txt
+      url: /wsgidav_test_file~$(session_id).txt

docs/sphinx/ug_reference.rst

@@ -25,9 +25,9 @@ config.verbose
 config.timeout
     Default: null
 config.max_errors
-    Default: null
+    Default: 0
 config.max_time
-    Default: null
+    Default: 0.0
 
 Session Configuration
 ---------------------

docs/sphinx/ug_use_cases.rst

@@ -0,0 +1,80 @@
+---------
+Use Cases
+---------
+
+..
+    .. toctree::
+    :hidden:
+
+Stressor may be used for several tasks.
+Currently we focus on web applications.
+
+Following a few recommendations, for a start.
+
+
+Stress Tests
+============
+
+- Define a script that covers relevant functionality of your target application.
+- Use ``duration: SECONDS`` and/or ``repeat: COUNT`` options for sequences,
+  so we have a long-running test.
+- Define ``sessions.users`` and ``sessions.count``, to simulate parallel user
+  access.
+- Optionally define ``monitor: true`` for selected activities, to collect extra
+  statistics.
+- Pass ``--monitor`` to view live proogress.
+
+
+CI Tests
+========
+
+Run stressor as part of a continous integration workflow, e.g. inside Jenkins.
+
+- Define a script that covers important functionality of your target application.
+- Set the ``config.max_errors: 1`` option (or pass the``--max-errors=1`` argument),
+  so the script will abort in case of errors as soon as possible.
+- Set the ``config.max_errors=SECONDS`` option (or pass the ``--max-errors=SECONDS``
+  argument), so unexpectedly long execution times will generate errors. |br|
+  Of course the sequences should not be time constrained using the
+  ``duration: SECONDS`` option for sequences in this case.
+- Pass ``--log FOLDER`` so results can be reviewed later.
+- Pass ``--verbose`` (``-v``) so logging will contain useful additional information.
+
+
+Benchmarks
+==========
+
+- Pass ``--quiet`` (``-q``), so logging will not impact performance.
+- Set the ``config.max_errors: 1`` option (or pass the``--max-errors=1`` argument),
+  so we fail fast on errors (unless sporadic errors are tolerated).
+- Define a script that runs for a given time, for example using the
+  ``duration: SECONDS`` option for sequences. |br|
+  Take note of 'activities per second per session' in the summary.
+- Or define a script that runs a number of sequences, for example using the
+  ``repeat: COUNT`` option for sequences. |br|
+  Take note of 'run time' in the summary.
+- Optionally define ``monitor: true`` for selected activities, to collect extra
+  statistics.
+
+
+Developing and Debugging Scripts
+================================
+
+- Pass ``--single`` so ``duration`` and ``repeat`` options are ignored.
+- Pass ``--verbose`` (``-v``) or even ``-vv`` to print more information about
+  requests and responses.
+- Set the ``config.max_errors: 1`` option (or pass the``--max-errors=1`` argument),
+  so we fail on the first error.
+- Optionally define ``debug: true`` for selected activities, to print extra
+  information.
+
+See `ug_writing_scripts`_ for details.
+
+
+Test Other Targets than Web-Applications
+========================================
+
+For example run a sequence of SQL statements against relational databases.
+
+This is **not yet implemented**, but should become possible using the plugin
+concept of a later version.

docs/sphinx/user_guide.rst

@@ -7,6 +7,7 @@ User Guide
 
     ug_quickstart.md
     ug_tutorial
+    ug_use_cases
     ug_writing_scripts
     ug_sample_stressor_yaml
     ug_reference

stressor/plugins/common.py

@@ -188,7 +188,7 @@ def execute(self, session, **expanded_args):
         # duration_2 = expanded_args.get("duration_2")
         # if duration_2 is not None:
         #     duration = random.uniform(duration, float(duration_2))
-        assert self._cur_duration
+        assert self._cur_duration is not None
         duration = self._cur_duration
         self._cur_duration = None
         if not session.dry_run:

tests/fixtures/test_monitor.yaml

@@ -15,7 +15,7 @@ config:
   verbose: 4
   base_url: http://127.0.0.1:8082
   timeout: 1
-  max_errors: false
+  max_errors: 0
 
 
 # Initial context value definitions.

tests/fixtures/test_noop.yaml

@@ -0,0 +1,39 @@
+file_version: stressor#0
+
+config:
+  name: Test no-op
+  tag: Not set (pass `-o tag:TAG_NAME` to override)
+  details: |
+    Contains only one sleep(0) activity. Use to benchmark max. throughput
+    of the stressor framework
+  verbose: 3
+  base_url: http://127.0.0.1:8082
+  timeout: 1
+  # max_time: 3.2
+
+context:
+
+sessions:
+  users: $load(users.yaml)
+  count: 10
+  # basic_auth: true
+  # threads_per_process: 5
+  # duration: 5
+
+# Define what actions should be performed by every session
+scenario:
+  - sequence: init
+  - sequence: main
+    duration: 30
+  - sequence: end
+
+
+# List of named action sequences. Used as building blocks for scenarios
+sequences:
+  # 'init' is the reserved name for the set-up sequence.
+  init:
+
+  main:
+    - activity: $sleep(0.0)
+
+  end: