@aj-shadow/actorjs-documentation-text 0.0.0-aj-beta.221

package/Documentation/actor-api/Document-global-actor.txt

@@ -0,0 +1,375 @@
+# **Actor API**
+[[API-STATUS=STABLE, ]]
+[[DOC-STATUS=MOSTLY, ]]
+
+[[NOTE={"guid":"e137cd45-0b0d-41aa-a561-3471a239a262"}]]
+[[ANCHOR={"id":"89dcb254-e370-46e5-b952-9ee185c1db1d","visible":true}]]
+## **Description**
+
+The core of the Actor API is the [[REF=, ABS_Actor]]s. When an [[REF=Actor, ABS_Actor]] is implemented, it is always inherited from one of five [[REF=Actor, ABS_Actor]] base classes. Each [[REF=Actor, ABS_Actor]] base class has its own purpose and properties.
+
+[[NOTE={"guid":"7b68d3c9-457c-458c-9d93-84922ebb4901"}]]
+[[ANCHOR={"id":"api-interfaces","visible":true}]]
+## **API Base Classes**
+* **[ActorOriginating](#ActorOriginating)**
+* **[ActorTerminating](#ActorTerminating)**
+* **[ActorProxy](#ActorProxy)**
+* **[ActorLocal](#ActorLocal)**
+* **[ActorCondition](#ActorCondition)**
+
+***
+
+[[NOTE={"guid":"ce8d06ea-6382-4c86-9dfe-05afe1934c3b"}]]
+[[ANCHOR={"id":"589b76ef-42b8-42c2-abad-b59ce818d238","visible":true}]]
+## **Implement the Execution States**
+When implementing an an [[REF=, ABS_Actor]], you will implement the [[REF=, ABS_Actor_State_Execution]] of the inherited [[REF=, ABS_Actor]]. You choose the [[REF=, ABS_Actor_State_Execution]] that you will implement. Non-implemented [[REF=, ABS_Actor_State_Execution]] can be removed from the code of the [[REF=, ABS_Actor]].
+
+The [[REF=, ABS_Actor_State_Execution]] are generator member functions. In most cases, you don't need to add the **yield** or **yield***. They will be automatically generated or identified by a naming convention. Read more in the APIs.
+
+[[NOTE={"guid":"9239f464-5d77-42cd-9b54-288df33c0a6e"}]]
+[[ANCHOR={"id":"ActorOriginating","visible":true}]]
+## **ActorOriginating** 
+An [[REF=, ABS_Actor_Originating]] is created by inheritance from **ActorApi.ActorOriginating**. See the [[REF=, CODE_Actor_Orig]] implementation.
+
+Can be executed in all [[REF=, ABS_Test_Case_Phases]].
+
+### **constructor**
+The constructor has one optional argument.
+```javascript
+
+
+class MyActorOrig extends ActorApi.ActorOriginating {
+  constructor(actorParts) {
+    super(actorParts);
+  }
+}
+
+```
+
+#### **Method Description**
+```table
+Config(classHeading: )
+
+|Parameters                                                                                                                                  |
+|Name      |Type                                                     |Default  |Description                                                  |
+|actorParts|[[REF=,MDN_string]] | [[REF=,MDN_strings]]|undefined|[[REF=,ABS_ActorPart]]s to be used by the [[REF=,ABS_Actor]].|
+```
+
+### **Execution States**
+The [[REF=, ABS_Actor_Originating]] has the following [[REF=, ABS_Actor_State_Execution]]:
+* ***data**
+* ***initClient**
+* ***run**
+* ***exit**
+
+[[NOTE={"guid":"b853898f-6faf-42c2-908d-22c440e6e33b"}]]
+[[ANCHOR={"id":"0bba2f5d-0e9c-438b-856f-7a6a1724fd09","visible":true}]]
+### **Example - NotImplementedOrig**
+
+```javascript
+
+
+
+const ActorApi = require('actor-api');
+
+
+class NotImplementedOrig extends ActorApi.ActorOriginating {
+  *data() {
+  }
+  
+  *initClient() {
+    this.connection = this.createConnection('[stack]');
+  }
+  
+  *run() {
+  }
+  
+  *exit() {
+    this.closeConnection(this.connection);
+  }
+}
+
+module.exports = NotImplementedOrig;
+
+```
+
+***
+
+[[NOTE={"guid":"0d98801f-b628-40fc-94cc-829319cba18c"}]]
+[[ANCHOR={"id":"ActorTerminating","visible":true}]]
+## **ActorTerminating** 
+An [[REF=, ABS_Actor_Terminating]] is created by inheritance from **ActorApi.ActorTerminating**. See the [[REF=, CODE_Actor_Term]] implementation.
+
+Can be executed in all [[REF=, ABS_Test_Case_Phases]].
+
+### **constructor**
+The constructor has two optional arguments.
+```javascript
+
+
+class MyActorTerm extends ActorApi.ActorTerminating {
+  constructor(actorParts, expectInterrupt) {
+    super(actorParts, expectInterrupt);
+  }
+}
+
+```
+
+#### **Method Description**
+```table
+Config(classHeading: )
+
+|Parameters                                                                                                                                                                                                     |
+|Name           |Type                                                     |Default  |Description                                                                                                                |
+|actorParts     |[[REF=,MDN_string]] | [[REF=,MDN_strings]]|undefined|[[REF=,ABS_ActorPart]]s to be used by the [[REF=,ABS_Actor]].                                                              |
+|expectInterrupt|[[REF=,MDN_boolean]]                                     |false    |The [[REF=,ABS_Actor]] expects to hang in the run method. This is to be able to verify that there is no message sent to it.|
+```
+
+[[NOTE={"guid":"a6f680b5-7ec7-4db5-b6f7-5c3416e5fe46"}]]
+[[ANCHOR={"id":"02c27c80-1d41-4ae3-baf3-e9b760c38677","visible":true}]]
+### **Execution States**
+The [[REF=, ABS_Actor_Terminating]] has the following [[REF=, ABS_Actor_State_Execution]]:
+* ***data**
+* ***initServer**
+* ***run**
+* ***exit**
+
+[[NOTE={"guid":"b64865cd-e799-4a3f-ad9a-d49e164c1b15"}]]
+[[ANCHOR={"id":"ac4e0ccf-5719-4c30-8994-c9a58e77edfd","visible":true}]]
+### **Example - NotImplementedTerm**
+
+```javascript
+
+
+
+const ActorApi = require('actor-api');
+
+
+class NotImplementedTerm extends ActorApi.ActorTerminating {
+  *data() {
+  }
+    
+  *initServer() {
+  }
+  
+  *run() {
+  }
+  
+  *exit() {
+  }
+}
+
+module.exports = NotImplementedTerm;
+
+```
+
+***
+
+[[NOTE={"guid":"330214a3-1267-42ea-af7b-8fb4fe852354"}]]
+[[ANCHOR={"id":"ActorProxy","visible":true}]]
+## **ActorProxy** 
+An [[REF=, ABS_Actor_Proxy]] is created by inheritance from **ActorApi.ActorProxy**. See the [[REF=, CODE_Actor_Proxy]] implementation.
+
+Can be executed in all [[REF=, ABS_Test_Case_Phases]].
+
+### **constructor**
+The constructor has one optional argument.
+```javascript
+
+
+class MyActorProxy extends ActorApi.ActorProxy {
+  constructor(actorParts) {
+    super(actorParts);
+  }
+}
+
+```
+
+#### **Method Description**
+```table
+Config(classHeading: )
+
+|Parameters                                                                                                                                  |
+|Name      |Type                                                     |Default  |Description                                                  |
+|actorParts|[[REF=,MDN_string]] | [[REF=,MDN_strings]]|undefined|[[REF=,ABS_ActorPart]]s to be used by the [[REF=,ABS_Actor]].|
+```
+
+### **Execution States**
+The [[REF=, ABS_Actor_Proxy]] has the following [[REF=, ABS_Actor_State_Execution]]:
+* ***data**
+* ***initServer**
+* ***initClient**
+* ***run**
+* ***exit**
+
+[[NOTE={"guid":"90ae2d2b-f6eb-42ab-bc68-59bb5c6d0622"}]]
+[[ANCHOR={"id":"e3de9117-8e53-42b9-a7b0-8aab2125c509","visible":true}]]
+### **Example - NotImplementedProxy**
+
+```javascript
+
+
+
+const ActorApi = require('actor-api');
+
+
+class NotImplementedProxy extends ActorApi.ActorProxy {
+  *data() {
+  }
+  
+  *initServer() {
+  }
+  
+  *initClient() {
+  }
+  
+  *run() {
+  }
+  
+  *exit() {
+  }
+}
+
+module.exports = NotImplementedProxy ;
+
+```
+
+***
+
+[[NOTE={"guid":"023b0b43-727f-4404-9841-8563a39587a9"}]]
+[[ANCHOR={"id":"ActorLocal","visible":true}]]
+## **ActorLocal** 
+An [[REF=, ABS_Actor_Local]] is created by inheritance from **ActorApi.ActorLocal**. See the [[REF=, CODE_Actor_Local]] implementation.
+
+Can be executed in all [[REF=, ABS_Test_Case_Phases]].
+
+### **constructor**
+The constructor has one optional argument.
+```javascript
+
+
+class MyActorLocal extends ActorApi.ActorLocal {
+  constructor(actorParts) {
+    super(actorParts);
+  }
+}
+
+```
+
+#### **Method Description**
+```table
+Config(classHeading: )
+
+|Parameters                                                                                                                                  |
+|Name      |Type                                                     |Default  |Description                                                  |
+|actorParts|[[REF=,MDN_string]] | [[REF=,MDN_strings]]|undefined|[[REF=,ABS_ActorPart]]s to be used by the [[REF=,ABS_Actor]].|
+```
+
+### **Execution States**
+The [[REF=, ABS_Actor_Local]] has the following [[REF=, ABS_Actor_State_Execution]]:
+* ***data**
+* ***run**
+
+[[NOTE={"guid":"feb17c66-a96a-419e-be17-2a972c567efb"}]]
+[[ANCHOR={"id":"5ee55912-29ee-4fcd-a862-4e8149654fad","visible":true}]]
+### **Example - NotImplementedLocal**
+
+```javascript
+
+
+
+const ActorApi = require('actor-api');
+
+
+class NotImplementedLocal extends ActorApi.ActorLocal {
+  data() {
+  }
+  
+  *run() {
+  }
+}
+
+module.exports = NotImplementedLocal;
+
+```
+
+***
+
+[[NOTE={"guid":"eb1afc63-34ce-4ff9-8752-5f55269aff14"}]]
+[[ANCHOR={"id":"ActorCondition ","visible":true}]]
+## **ActorCondition** 
+An [[REF=, ABS_Actor_Condition]] is created by inheritance from **ActorApi.ActorCondition**. See the [[REF=, CODE_Actor_Condition]] implementation.
+
+Can be executed only in [[REF=, ABS_Test_Case_Phase_Precondition]] and [[REF=, ABS_Test_Case_Phase_Postcondition]]. The  [[REF=, ABS_Actor_State_Execution]] starting with ***pre*** will be executed in the [[REF=, ABS_Test_Case_Phase_Precondition]] and the  [[REF=, ABS_Actor_State_Execution]] starting with ***post*** will be executed in the [[REF=, ABS_Test_Case_Phase_Postcondition]].
+
+### **constructor**
+The constructor has one optional argument.
+```javascript
+
+
+class MyActorCond extends ActorApi.ActorCondition {
+  constructor(actorParts) {
+    super(actorParts);
+  }
+}
+
+```
+
+#### **Method Description**
+```table
+Config(classHeading: )
+
+|Parameters                                                                                                                                  |
+|Name      |Type                                                     |Default  |Description                                                  |
+|actorParts|[[REF=,MDN_string]] | [[REF=,MDN_strings]]|undefined|[[REF=,ABS_ActorPart]]s to be used by the [[REF=,ABS_Actor]].|
+```
+
+### **Execution States**
+The [[REF=, ABS_Actor_Proxy]] has the following [[REF=, ABS_Actor_State_Execution]]:
+* ***data**
+* ***initClientPre**
+* ***runPre**
+* ***exitPre**
+* ***initClientPost**
+* ***runPost**
+* ***exitPost**
+
+[[NOTE={"guid":"952884d4-6f80-4dc2-ba9a-98bc3f993a99"}]]
+[[ANCHOR={"id":"f291f23a-65f6-497b-8be2-e74c65ecc52a","visible":true}]]
+### **Example - NotImplementedCond**
+
+```javascript
+
+
+
+const ActorApi = require('actor-api');
+
+
+class NotImplementedCond extends ActorApi.ActorCondition {
+  *data() {
+  }
+  
+  *initClientPre() {
+  }
+  
+  *runPre() {
+  }
+  
+  *exitPre() {
+  }
+  
+  *initClientPost() {
+  }
+  
+  *runPost() {
+  }
+  
+  *exitPost() {
+  }
+}
+
+module.exports = NotImplementedCond;
+
+```
+
+***

package/Documentation/actor-api/Document-global-async.txt

@@ -0,0 +1,176 @@
+# **Async API**
+[[API-STATUS=STABLE, ]]
+[[DOC-STATUS=PARTLY, ]]
+
+[[NOTE={"guid":"a88191fa-0769-48d2-bc42-48a43258800f"}]]
+[[ANCHOR={"id":"6bc88358-9634-4857-bcf7-9e94a2c2da6b","visible":true}]]
+## **Description**
+
+Enables the use of the keyword ***async*** in [[REF=, ABS_Actor]]s. The [[REF=, ABS_Actor_State_Execution]] are implemented as a generator members function, allowing the API methods to be asynchronous.
+
+Async API implementation starts in [[REF=, CODE_Async]].
+
+[[NOTE={"guid":"96173c22-0562-4df7-b1af-9f2a92d926ac"}]]
+[[ANCHOR={"id":"2aa29941-066d-4bc9-a2c0-ea72d73432a7","visible":true}]]
+## **API Methods**
+* **[*async](#async-api-async)**
+* **[*callback](#async-api-callback)**
+* **[require](#async-api-require)**
+
+***
+[[NOTE={"guid":"8f875ebd-f6af-484b-b6dd-6254dc5a4bdb"}]]
+[[ANCHOR={"id":"async-api-async","visible":true}]]
+### ***async**
+```
+this.async(asyncFunction)
+```
+
+[[NOTE={"guid":"eb902bfa-18b4-48d6-a1b6-ff5075a3c027"}]]
+[[ANCHOR={"id":"81adbcc3-ab24-4e97-b343-16a61a3358e8","visible":true}]]
+#### **Method Description**
+
+Calls an async function and waits for it to end.
+```table
+Config(classHeading: )
+
+|Parameters                                                                                    |
+|Name         |Type                             |Description                                   |
+|asyncFunction|***async*** [[REF=,MDN_Function]]|Async function that can use the keyword await.|
+```
+
+```table
+Config(classHeading: )
+
+|Returns                                   |
+|Type           |Description               |
+|<**any**>|The resulting ***value***.|
+```
+
+```table
+Config(classHeading: )
+
+|Async                    |
+|type      |Description   |
+|**yield***|auto generated|
+```
+
+[[NOTE={"guid":"a3725118-cd79-4688-9cf4-bb9c9bca492a"}]]
+[[ANCHOR={"id":"b33e7c3e-0069-4bfd-b1b2-b524e9628d82","visible":true}]]
+#### **Example using async**
+
+```javascript
+
+*run() {
+  this.async(async () => {
+    const page = await this.getPage();
+    await page.click('OK');
+  });
+}
+
+```
+
+[[NOTE={"guid":"3af15f8a-65a7-4d0e-b323-7a83d5553214"}]]
+[[ANCHOR={"id":"6ef00d6a-5935-44c1-a3c1-ae8c4fb57e72","visible":true}]]
+```javascript
+
+*run() {
+  this.async(this._run.bind(this));
+}
+
+async _run() {
+  const page = await this.getPage();
+  await page.click('OK');
+}
+
+```
+
+[[NOTE={"guid":"b8d73287-f036-43f7-bb13-d31593d470b0"}]]
+[[ANCHOR={"id":"348bbb55-c10c-4259-b964-87e83f775d1f","visible":true}]]
+#### **Test Cases using async**
++ [DocActorApiAsyncArrowFunction](/../test-cases/Actor/Doc/DocActorApiAsyncArrowFunction)
++ [DocActorApiAsyncMemberFunction](/../test-cases/Actor/Doc/DocActorApiAsyncMemberFunction)
+
+***
+
+[[NOTE={"guid":"d38a1cfd-056f-4395-89a6-f2be8faf1149"}]]
+[[ANCHOR={"id":"async-api-callback","visible":true}]]
+### ***callback**
+```
+this.callback(callbackFunction)
+```
+
+[[NOTE={"guid":"fee028cd-bc08-4f87-81ec-aa08f0617e27"}]]
+[[ANCHOR={"id":"bbf94812-00b9-408b-8520-af3f0e040fa1","visible":true}]]
+#### **Method Description**
+
+Calls a function and waits for it to make a callback.
+```table
+Config(classHeading: )
+
+|Parameters                                                                                                                            |
+|Name                |Type                 |Description                                                                                |
+|callbackFunction(cb)|[[REF=,MDN_Function]]|Function that makes a callback when it is ready. cb is a [[REF=,MDN_Function]](err, value).|
+```
+
+```table
+Config(classHeading: )
+
+|Returns                                   |
+|Type           |Description               |
+|<**any**>|The resulting ***value***.|
+```
+
+```table
+Config(classHeading: )
+
+|Async                    |
+|type      |Description   |
+|**yield***|auto generated|
+```
+
+[[NOTE={"guid":"c1809ea4-c6fa-4e98-b522-493a9b8cf212"}]]
+[[ANCHOR={"id":"6778ac13-2022-4efc-afa5-4a15eb336f4d","visible":true}]]
+#### **Example using async**
+
+```javascript
+
+*run() {
+  const data = this.callback((cb) => {
+    cb(undefined, 'Callback arrow return value.');
+  });
+}
+
+```
+
+[[NOTE={"guid":"99bc0470-1add-4a92-97ff-c2aa0be13a75"}]]
+[[ANCHOR={"id":"c85e00d2-1c85-406a-b58a-47ca3b5f2937","visible":true}]]
+```javascript
+
+*run() {
+  const data = this.callback(this.callbackFunc.bind(this));
+  VERIFY_VALUE('Callback member return value.', data);
+}
+  
+callbackFunc(cb) {
+  cb(undefined, 'Callback member return value.');
+}
+
+```
+
+[[NOTE={"guid":"5c33e230-55f7-4416-a871-acf34774881d"}]]
+[[ANCHOR={"id":"9762a9ce-ea7a-4b43-aa70-8b0015a8c04d","visible":true}]]
+#### **Test Cases using async**
++ [DocActorApiCallbackArrowFunction](/../test-cases/Actor/Doc/DocActorApiCallbackArrowFunction)
++ [DocActorApiCallbackMemberFunction](/../test-cases/Actor/Doc/DocActorApiCallbackMemberFunction)
+
+***
+
+[[NOTE={"guid":"fedaa280-55f6-41a2-a5e4-ab3df0dc41d6"}]]
+[[ANCHOR={"id":"async-api-require","visible":true}]]
+### **require**
+```
+this.require(nodejsApi)
+```
+
+#### **Method Description**
+Creates a object from the NodejsApi. The NodejsApi wraps nodejs Api:s and "***yieldifies***" them.