Apama Analytics EPL Apps tools for 10.7.0.1

doc/pydoc/autodocgen/apamax.eplapplications.basetest.html

@@ -117,6 +117,12 @@ <h2>ApamaC8YBaseTest<a class="headerlink" href="#apamac8ybasetest" title="Permal
 If this tag is not defined (or the value is an empty string) then all the mon files in project.EPL_APPS directory are returned.</p>
 </dd></dl>
 
+<dl class="py method">
+<dt id="apamax.eplapplications.basetest.ApamaC8YBaseTest.prepareTenant">
+<code class="sig-name descname">prepareTenant</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/apamax/eplapplications/basetest.html#ApamaC8YBaseTest.prepareTenant"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#apamax.eplapplications.basetest.ApamaC8YBaseTest.prepareTenant" title="Permalink to this definition">¶</a></dt>
+<dd><p>Prepares the tenant for a test by deleting all devices created by previous tests, and clearing all active alarms.</p>
+</dd></dl>
+
 <dl class="py method">
 <dt id="apamax.eplapplications.basetest.ApamaC8YBaseTest.setup">
 <code class="sig-name descname">setup</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/apamax/eplapplications/basetest.html#ApamaC8YBaseTest.setup"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#apamax.eplapplications.basetest.ApamaC8YBaseTest.setup" title="Permalink to this definition">¶</a></dt>
@@ -161,6 +167,20 @@ <h2>LocalCorrelatorSimpleTest<a class="headerlink" href="#localcorrelatorsimplet
 using GET request to <a class="reference external" href="http://correlator.host:correlator.port">http://correlator.host:correlator.port</a></p>
 </dd></dl>
 
+<dl class="py method">
+<dt id="apamax.eplapplications.basetest.LocalCorrelatorSimpleTest.setup">
+<code class="sig-name descname">setup</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/apamax/eplapplications/basetest.html#LocalCorrelatorSimpleTest.setup"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#apamax.eplapplications.basetest.LocalCorrelatorSimpleTest.setup" title="Permalink to this definition">¶</a></dt>
+<dd><p>Contains setup actions to be executed before the test is executed.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">setup</span></code> method may be overridden by individual test classes, or (more commonly) in a custom <code class="xref py py-obj docutils literal notranslate"><span class="pre">BaseTest</span></code> 
+subclass that provides common functionality for multiple individual tests. However before implementing a custom 
+BaseTest subclass with its own setup() method, consider whether the PySys concept of test plugins would meet 
+your needs.</p>
+<p>If you do override this method, be sure to call <code class="docutils literal notranslate"><span class="pre">super(BASETEST_CLASS_HERE,</span> <span class="pre">self).setup()</span></code> to allow the 
+setup commands from the base test to run.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">setup</span></code> throws an exception, the <code class="xref py py-obj docutils literal notranslate"><span class="pre">cleanup</span></code> method will still be called, to allow for clean up resources 
+that were already allocated.</p>
+</dd></dl>
+
 <dl class="py method">
 <dt id="apamax.eplapplications.basetest.LocalCorrelatorSimpleTest.validate">
 <code class="sig-name descname">validate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/apamax/eplapplications/basetest.html#LocalCorrelatorSimpleTest.validate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#apamax.eplapplications.basetest.LocalCorrelatorSimpleTest.validate" title="Permalink to this definition">¶</a></dt>
@@ -184,6 +204,13 @@ <h2>EPLAppsSimpleTest<a class="headerlink" href="#eplappssimpletest" title="Perm
 directory or with the EPLApps directive using EPL applications to run each test.</p>
 </dd></dl>
 
+<dl class="py method">
+<dt id="apamax.eplapplications.basetest.EPLAppsSimpleTest.prepareTenant">
+<code class="sig-name descname">prepareTenant</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/apamax/eplapplications/basetest.html#EPLAppsSimpleTest.prepareTenant"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#apamax.eplapplications.basetest.EPLAppsSimpleTest.prepareTenant" title="Permalink to this definition">¶</a></dt>
+<dd><p>Prepares the tenant for a test by deleting all devices created by previous tests, deleting all EPL Apps which have been uploaded by tests, and clearing all active alarms.</p>
+<p>This is done first so that there’s no possibility existing test apps raising alarms or creating devices</p>
+</dd></dl>
+
 <dl class="py method">
 <dt id="apamax.eplapplications.basetest.EPLAppsSimpleTest.setup">
 <code class="sig-name descname">setup</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="reference internal" href="../_modules/apamax/eplapplications/basetest.html#EPLAppsSimpleTest.setup"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#apamax.eplapplications.basetest.EPLAppsSimpleTest.setup" title="Permalink to this definition">¶</a></dt>

doc/pydoc/genindex.html

@@ -47,6 +47,7 @@ <h1 id="index">Index</h1>
  | <a href="#G"><strong>G</strong></a>
  | <a href="#L"><strong>L</strong></a>
  | <a href="#M"><strong>M</strong></a>
+ | <a href="#P"><strong>P</strong></a>
  | <a href="#R"><strong>R</strong></a>
  | <a href="#S"><strong>S</strong></a>
  | <a href="#U"><strong>U</strong></a>
@@ -221,6 +222,18 @@ <h2 id="M">M</h2>
   </ul></td>
 </tr></table>
 
+<h2 id="P">P</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="autodocgen/apamax.eplapplications.basetest.html#apamax.eplapplications.basetest.ApamaC8YBaseTest.prepareTenant">prepareTenant() (apamax.eplapplications.basetest.ApamaC8YBaseTest method)</a>
+
+      <ul>
+        <li><a href="autodocgen/apamax.eplapplications.basetest.html#apamax.eplapplications.basetest.EPLAppsSimpleTest.prepareTenant">(apamax.eplapplications.basetest.EPLAppsSimpleTest method)</a>
+</li>
+      </ul></li>
+  </ul></td>
+</tr></table>
+
 <h2 id="R">R</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
@@ -236,6 +249,8 @@ <h2 id="S">S</h2>
 
       <ul>
         <li><a href="autodocgen/apamax.eplapplications.basetest.html#apamax.eplapplications.basetest.EPLAppsSimpleTest.setup">(apamax.eplapplications.basetest.EPLAppsSimpleTest method)</a>
+</li>
+        <li><a href="autodocgen/apamax.eplapplications.basetest.html#apamax.eplapplications.basetest.LocalCorrelatorSimpleTest.setup">(apamax.eplapplications.basetest.LocalCorrelatorSimpleTest method)</a>
 </li>
       </ul></li>
   </ul></td>

doc/pydoc/testing-epl.html

@@ -56,15 +56,15 @@ <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to t
 <ul class="simple">
 <li><p>Creating device simulators.</p></li>
 <li><p>Sending mock data to Cumulocity IoT.</p></li>
-<li><p>Listening for events that the EPL app should produce; and/or</p></li>
+<li><p>Listening for events that the EPL app should produce.</p></li>
 <li><p>Querying Cumulocity IoT for any objects created by the EPL app.</p></li>
 </ul>
-<p>This can all be done using additional EPL apps that run parallel to the EPL app that we wish to test for correctness. This document will demonstrate some of the common processes involved in writing these additional EPL apps that test your exising EPL apps, while outlining some of the conventions for writing tests that best utilize the PySys test framework provided in the SDK.</p>
+<p>This can all be done using additional EPL apps that run parallel to the EPL app that we wish to test for correctness. This document will demonstrate some of the common processes involved in writing these additional EPL apps that test your existing EPL apps, while outlining some of the conventions for writing tests that best utilize the PySys test framework provided in the SDK.</p>
 </div>
 <div class="section" id="creating-device-simulators">
 <h2>Creating device simulators<a class="headerlink" href="#creating-device-simulators" title="Permalink to this headline">¶</a></h2>
 <p>All measurements and alarms in Cumulocity IoT must be associated with a source. Devices in Cumulocity IoT are represented by managed objects, each of which has a unique identifier. When sending measurement or alarm events, the <code class="docutils literal notranslate"><span class="pre">source</span></code> field of these events must be set to a identifier of a managed object in Cumulocity IoT. Therefore, in order to send measurements from our test EPL app, it must create a <code class="docutils literal notranslate"><span class="pre">ManagedObject</span></code> device simulator to be the source of these measurements.</p>
-<p>If you are using the PySys framework to <a class="reference internal" href="using-pysys.html#test-in-cloud"><span class="std std-ref">run tests in the cloud</span></a>, any devices created by your tests should be named with prefix “PYSYS_”, and have the <code class="docutils literal notranslate"><span class="pre">c8y_IsDevice</span></code> property. These indicators are what the framework uses to identify which devices should be deleted following a test. Note that deleting a device in Cumulocity IoT will also delete any alarms or measurements associated with that device so the cleanup from a test is done when another test is next run in the cloud again.</p>
+<p>If you are using the PySys framework to <a class="reference internal" href="using-pysys.html#test-in-cloud"><span class="std std-ref">run tests in the cloud</span></a>, any devices created by your tests should be named with prefix “PYSYS_”, and have the <code class="docutils literal notranslate"><span class="pre">c8y_IsDevice</span></code> property. These indicators are what the framework uses to identify which devices should be deleted following a test. Note that deleting a device in Cumulocity IoT will also delete any alarms or measurements associated with that device so the cleanup from a test is done when another test is next run.</p>
 <p>To see how this can be done, have a look at the <code class="docutils literal notranslate"><span class="pre">createNewDevice</span></code> action below:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">action</span> <span class="n">createNewDevice</span><span class="p">(</span><span class="n">string</span> <span class="n">name</span><span class="p">)</span> <span class="n">returns</span> <span class="n">integer</span>
 <span class="p">{</span>

doc/pydoc/using-pysys.html

@@ -53,7 +53,7 @@ <h1>Using PySys to test your EPL apps<a class="headerlink" href="#using-pysys-to
 <div class="section" id="introduction">
 <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
 <p>PySys is a testing framework that provides a way to test your applications.</p>
-<p>See <a class="reference external" href="https://pysys-test.github.io/pysys-test/">PySys Documentation</a> for details on how the framework can be used and the facilities it contains.</p>
+<p>See <a class="reference external" href="https://pysys-test.github.io/pysys-test/">PySys Documentation</a> for details on installation and how the framework can be used and the facilities it contains.</p>
 </div>
 <div class="section" id="testing-in-the-cumulocity-iot-cloud">
 <span id="test-in-cloud"></span><h2>Testing in the Cumulocity IoT cloud<a class="headerlink" href="#testing-in-the-cumulocity-iot-cloud" title="Permalink to this headline">¶</a></h2>
@@ -163,6 +163,11 @@ <h3>Running the test<a class="headerlink" href="#id1" title="Permalink to this h
 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pysys run TestLocalCorrelator
 </pre></div>
 </div>
+<p>Whenever you run a test using a local correlator, before the test is executed:</p>
+<ul class="simple">
+<li><p>All active Alarms in your Cumulocity IoT tenant are cleared.</p></li>
+<li><p>Any devices created by previous tests (which are identified by the device name having prefix “PYSYS_”) are deleted from your tenant.</p></li>
+</ul>
 </div>
 </div>
 <div class="section" id="advanced-tests">

doc/testing-epl.rst

@@ -10,16 +10,16 @@ The behavior of most EPL apps usually consists of receiving data, sending measur
 
 + Creating device simulators.
 + Sending mock data to Cumulocity IoT.
-+ Listening for events that the EPL app should produce; and/or
++ Listening for events that the EPL app should produce.
 + Querying Cumulocity IoT for any objects created by the EPL app.
 
-This can all be done using additional EPL apps that run parallel to the EPL app that we wish to test for correctness. This document will demonstrate some of the common processes involved in writing these additional EPL apps that test your exising EPL apps, while outlining some of the conventions for writing tests that best utilize the PySys test framework provided in the SDK.  
+This can all be done using additional EPL apps that run parallel to the EPL app that we wish to test for correctness. This document will demonstrate some of the common processes involved in writing these additional EPL apps that test your existing EPL apps, while outlining some of the conventions for writing tests that best utilize the PySys test framework provided in the SDK. 
 
 Creating device simulators
 ===========================
 All measurements and alarms in Cumulocity IoT must be associated with a source. Devices in Cumulocity IoT are represented by managed objects, each of which has a unique identifier. When sending measurement or alarm events, the ``source`` field of these events must be set to a identifier of a managed object in Cumulocity IoT. Therefore, in order to send measurements from our test EPL app, it must create a ``ManagedObject`` device simulator to be the source of these measurements.
 
-If you are using the PySys framework to :ref:`run tests in the cloud <test-in-cloud>`, any devices created by your tests should be named with prefix "PYSYS\_", and have the ``c8y_IsDevice`` property. These indicators are what the framework uses to identify which devices should be deleted following a test. Note that deleting a device in Cumulocity IoT will also delete any alarms or measurements associated with that device so the cleanup from a test is done when another test is next run in the cloud again. 
+If you are using the PySys framework to :ref:`run tests in the cloud <test-in-cloud>`, any devices created by your tests should be named with prefix "PYSYS\_", and have the ``c8y_IsDevice`` property. These indicators are what the framework uses to identify which devices should be deleted following a test. Note that deleting a device in Cumulocity IoT will also delete any alarms or measurements associated with that device so the cleanup from a test is done when another test is next run. 
 
 To see how this can be done, have a look at the ``createNewDevice`` action below::
 

doc/using-pysys.rst

@@ -8,7 +8,7 @@ Introduction
 
 PySys is a testing framework that provides a way to test your applications. 
 
-See `PySys Documentation <https://pysys-test.github.io/pysys-test/>`_ for details on how the framework can be used and the facilities it contains. 
+See `PySys Documentation <https://pysys-test.github.io/pysys-test/>`_ for details on installation and how the framework can be used and the facilities it contains. 
 
 .. _test-in-cloud:
 
@@ -158,6 +158,11 @@ Run the test from within the samples directory by using the following command:
 
     pysys run TestLocalCorrelator
 
+Whenever you run a test using a local correlator, before the test is executed:
+
++ All active Alarms in your Cumulocity IoT tenant are cleared.
++ Any devices created by previous tests (which are identified by the device name having prefix "PYSYS\_") are deleted from your tenant.
+
 Advanced tests
 ==============
 

readme.rst

@@ -9,8 +9,6 @@ you to script uploads of your EPL apps and manage them for CI/CD use cases.
 It also provides extensions to the PySys test framework to allow you 
 to simply write tests for your EPL apps and to run them automatically.
 
-See <http://www.apamacommunity.com/docs> <https://cumulocity.com/guides/apama> for further docs.
-
 Disclaimer
 ----------
 These tools are provided as-is and without warranty or support. They do not 
@@ -39,6 +37,15 @@ To find out how to write a test for your EPL apps please look at `Writing tests
 
 In order to view documentation on classes for PySys helpers for Apama EPL Apps please see: `PySys helpers <https://SoftwareAG.github.io/apama-eplapps-tools/doc/pydoc/autodocgen/apamax.eplapplications.html#module-apamax.eplapplications>`_.
 
+See <http://www.apamacommunity.com/docs> <https://cumulocity.com/guides/apama> <https://pysys-test.github.io/pysys-test/> for further docs.
+
+System requirements
+-------------------
+This SDK requires an installation of Python 3.7+ and will run on either Windows or Linux.
+
+The EPL apps test framework requires you to have an installation of PySys. See `PySys Documentation <https://pysys-test.github.io/pysys-test/>`_ for details. If you want the option of running tests locally, you will also need an installation of Apama, which can be obtained from <http://www.apamacommunity.com/downloads/>. If you choose to install Apama, you may skip the manual installation of Python and PySys as both are shipped with Apama. 
+
+
 Repository structure
 ====================
 

scripts/eplapp.cmd

@@ -15,7 +15,23 @@ setlocal
 
 set THIS_SCRIPT=%~$PATH:0
 call :getpath %THIS_SCRIPT
-py.exe "%THIS_DIR%\eplapp.py" %* 
+if not defined APAMA_HOME (goto APAMA_HOME_UNDEFINED)
+
+set "PATH=%APAMA_HOME%\third_party\python;%PATH%"
+python.exe "%THIS_DIR%\eplapp.py" %* 
+goto CHECK
+
+:APAMA_HOME_UNDEFINED
+WHERE python >NUL 2>&1
+if errorlevel 1 (goto PY_UNDEFINED)
+python.exe "%THIS_DIR%\eplapp.py" %* 
+goto CHECK
+
+:PY_UNDEFINED
+echo Please add an appropriate Python 3 version to your path. Please refer to the System requirements section of the documentaion.
+goto END
+
+:CHECK
 if NOT %errorlevel% == 0 ( 
 	EXIT /B %errorlevel%
 )