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

package/Documentation/Document-global-test-environment-overview.txt

@@ -0,0 +1,15 @@
+# Test Environment Overview
+
+***`TBD`***
+
++ [Navigation pane](navigation-pane)
++ Tools
++ Editors
++ Addressing
+
+From the [start](/start) page of ActorJs, the different parts of the Test Environment are reached through the [Navigation pane](navigation-pane) to the left in the browser window.
+
+
+
+
+

package/Documentation/Document-global-the-architecture.txt

@@ -0,0 +1,51 @@
+# **The Architecture**
+
+[[ANCHOR={"id":"the-architecture-execution-abstractions","visible":true}]]
+[[NOTE={"guid":"3ab223fa-e3b0-4ba0-be36-cb2e5743dab6"}]]
+## **Simplified class diagram**
+
+Below we show the core classes for the implementation of the ActorJs execution engine, and who creates them.
+
+```node
+Config(nodeWidth: 100, nodeHeight: 30, nodeWidthBetween: 25, nodeHeightBetween: 25, widthBias: 30, heightBias: 30, border: true, backgroundColor: default)
+
+Nodes[, , ActorPart(; ; PaleGreen), Message(; ; PaleGreen), Decoder(; ; #FFFF66)]
+Nodes[TestSuite, TestCase, Actor(; ; PaleGreen), Connection(; ; #FFFF66), Encoder(; ; #FFFF66)]
+Nodes[Test Data, Verification Data, Address, Content, ConnectionWorker(; ; #FFFF66)]
+
+
+Actor => ActorPart[, , , false]: 
+TestSuite => TestCase[, , , false]: 
+TestCase => Actor[, , , false]: 
+Actor => Message[, , , false]: 
+Actor => Connection[, right, left, false]: 
+Connection => ConnectionWorker[, bottom, , false]: 
+Connection => Decoder[, , , false]: 
+Connection => Encoder[, , , false]: 
+Actor => Test Data[, bottom, , false]: 
+Actor => Verification Data[, bottom, , false]: 
+Actor => Address[, , , false]: 
+Actor => Content[, , , false]: 
+```
+
+
+* **White boxes**: Created by ActorJs.
+* **Green boxes**: Created by the users, using a base class from ActorJs.
+* **Yellow boxes**: Usually created by ActorJs, but can also be created by the users.
+
+See the education [[REF=, VIDEOS]] about how to create the different abstractions.
+
+When executing a [[REF=, ABS_Test_Case]] or a [[REF=, ABS_Test_Suite]], the execution uses the following components (links to the implementation): 
+* [[REF=, CODE_Test_Suite]]
+* [[REF=, CODE_Test_Case]]
+* [[REF=, CODE_Test_Data]]
+* [[REF=, CODE_Verification_Mandatory]]
+* [[REF=, CODE_Verification_Optional]]
+* [[REF=, CODE_Verification_Value]]
+* [[REF=, CODE_Content]]
+* [[REF=, CODE_Actor]]
+* [[REF=, CODE_ActorPartPre]]
+* [[REF=, CODE_ActorPartPost]]
+
+
+

package/Documentation/Document-global-the-development-environment.txt

@@ -0,0 +1,5 @@
+# **The Development Environment**
+ActorJs is a server that you run locally on your own computer. Simply download ActorJs from npm [@actorjs/actorjs](https://www.npmjs.com/package/@actorjs/actorjs) and run it as a web app in a browser. The results you produce in ActorJs are stored in your local [[REF=repos, ABS_Repo]]. ActorJs connects to the ActorJs cloud for services.
+
+![](/abs-images/images/Development-Environment.png)
+

package/Documentation/Document-global-the-test-environment.txt

@@ -0,0 +1,15 @@
+# **The Test Environment**
+The Test Environment has three purposes:
+* Build and maintain [[REF=, ABS_Test_Case]]s.
+* Execute [[REF=, ABS_Test_Case]]s in a development environment to speed up development.
+* Perform Regression Tests in a CI to stay continuously updated on the current status of the [[REF=, ABS_System_To_Test]].
+
+## **Test Cases and Actors**
+ActorJs simulates processes that allow you to trigger, mock, and intercept all kinds of signaling. You can replace nodes, processes, hardware, and more with [[REF=Actor, ABS_Actor]]s. An [[REF=Actor, ABS_Actor]] acts as a small piece of the node, process, hardware, or other instance that the [[REF=Actor, ABS_Actor]] is replacing.
+
+
+![](/abs-images/images/Test-Environment.png)
+
+## **The same Test Cases for development and regression**
+ActorJs supports [[REF=Address separation, ABS_Addressing]], which means that the same [[REF=, ABS_Test_Case]] can run on a local machine together with a development version of the [[REF=, ABS_System_Under_Test]], with only one IP address. Alternatively, ActorJs can run the same [[REF=, ABS_Test_Case]] against an actual production version of the [[REF=, ABS_System_Under_Test]] with many different nodes/machines and an unlimited number of IP addresses and networks.
+

package/Documentation/Document-global-think-ahead.txt

@@ -0,0 +1,35 @@
+# **Think Ahead**
+Staying in front of the pack requires a lot of soul-searching from a development organization. What questions should development be asking itself -- and answering? Here are a few.
+
+#### **Is our test environment good enough, and how do we keep it that way?**
+* **Is our test environment fully automated? Does it support push and pull -- if one developer pushes a test case, can a coworker simply pull that code and run the test case?**<br /> All manual configurations are error-prone, unpleasant to work with, and costly.
+* **Does our test environment implement a full data separation strategy?**<br /> If not, test cases will not be flexible or maintainable. Example: a specific integer is stored in hundreds of test cases. Changing that integer in one means updating all affected test cases.
+* **Does testing increase the implementation time required for our product? And does it feel like a necessary evil?**<br /> It doesn't have to hurt. A good test environment will help you speed up processes and make the work much more fun!
+* **Are our test cases fast?**<br /> They have to be, or their cost will be higher than their returns. 
+* **Are managers and architects saying that a few seconds for a test case is fast enough?**<br /> Sure, it may sound fast, but let's do the math. A thousand test cases at three seconds per test case will take 50 minutes -- an eternity in a competitive development race. Even a test case with complex signalling to several surrounding systems should take a few milliseconds at most.
+
+#### **What's our test strategy, and is it working?**
+* **Sometimes, management says that the solution is to test everything.**<br /> From a mathematical perspective, this is simply not doable.
+* **Is our organization reluctant to test?**<br /> This is understandable in a way. If a lot of test cases are built using the wrong abstractions, new requirements can produce significant costs for rebuilding test cases, and a lot of test cases will be discarded. With this in mind, it's no wonder that some hesitate to test.
+* **Are we expecting the organization to verify as much as possible in every test case?**<br />This can lead to trouble. In an ideal world, one bug would make one test case fail, and it would be easy to find the problem. If one bug can make hundreds of test cases fail, it could send management following the CI into panic mode.
+
+#### **Is our product truly built for testing?**
+* **Is the build time of our product optimized?**<br /> Who hasn't heard the claim, "It builds fast enough"? Do you agree? Does everyone in management understand the cost and how it has the potential to slow down our work?
+* **Is the installation automated, fast, and stable?**<br /> It must be, or problems will pile up, work will slow to a snail's pace, and costs will increase dramatically.
+* **Do we have data separation when installing the product? In other words, can we install an infinite number of instances of the product with different configurations, different data, and different surrounding systems, with little effort?**
+Flexibility is the key, and not being able to adapt quickly to different installation scenarios becomes expensive and tiresome. New test cases can force the organization to build new installation scripts.
+* **Can we reduce our product -- can we install our multi-server system on a single computer?** If not, product development and test will slow down significantly, and it can be costly if several computers are needed for test. In the worst case, developers will not be able to test and testers will have to test in specially built labs. Talk about a snail's pace!
+* **Can we change the product configuration live, without delay or restart?**<br /> Let's do some math again. At 10 seconds to restart the product when changing a configuration, and 100 test cases that need to be updated, the reconfiguration will cost 10 s * 100 = 1000 s. That's a loss of more than 16 minutes for just 100 test cases.
+* **Can we decrease timeouts on the product to almost 0 seconds?**<br /> Example: If the timeout range for a function is 10 - 30 seconds, and when testing the function, the timeout is brought down to 10 seconds, then 100 test cases will test cost 10 s * 100 = 1000 s. That's another 16 minutes lost on just 100 test cases. 
+
+With CI running repeatedly throughout an entire working day, failing to address just one of these issues adds up to hours of lost time, every day. A company must ask itself whether it is willing to accept that cost, and how doing that will keep the company ahead of the competition.
+It's also important to remember that asking these tough questions and finding answers is one way to retain the best development talent on the market. Happy developers make great products.
+
+#### **The "illusion of health" or "disease insight"?**<br />
+It's tempting to assume that all is well because build times seem short or timeouts appear reasonable. However, staying ahead means thinking ahead, all the time. Some will argue that "we sell products, not test cases or CI", but a product is only as good as its weakest testing. 
+It's also easy to believe that these thorny problems are too difficult to solve, and that the company can soldier on with its current strategies. 
+So what's the solution? Awareness doesn't mean having to give up. Above all, companies must continually scrutinize the test environment and CI, ask difficult questions, prioritize, and solve problems step by step. The remedies, tools, and expertise are out there to overcome testing challenges.
+
+
+[[IE=Think ahead -- determine your strategy for speed and cost of development, test and maintenance of a product, and product quality, and get the right tools to make it happen!]]
+

package/Documentation/Document-global-thinking-in-actors-unlimited.txt

@@ -0,0 +1 @@
+# Thinking in Actors Unlimited

package/Documentation/Document-global-what-is-a-stack.txt

@@ -0,0 +1,2 @@
+# What is a stack?
+## Please Edit

package/Documentation/Document-global-why-actorjs.txt

@@ -0,0 +1,52 @@
+# **Why ActorJs?**
+
+In ActorJs it is so simple to execute [[REF=, ABS_Test_Case]]s. Developers, testers, managers, executive officers...everyone can execute them. Our CEO does!
+
+[[ANCHOR={"id":"fedb1e87-290a-48b1-b4ca-8dff91fd1a08","visible":true}]]
+[[NOTE={"guid":"1ae50f7f-90c8-4779-9d97-59e20e799d94"}]]
+
+### **Simulators are very complex to use and difficult to automate**
+Using simulators to isolate a [[REF=, ABS_System_Under_Test]] adds significant complexity to your environment. The simulators must not only be part of your environment; and they must be fully integrated into your environment. Issues that must be addressed include:
+* **Environment:** the simulator must be part of your environment. When setting up a new lab, the simulator must be automatically installed and configured. All developers and testers must be able to use the simulator and it must be possible to automate the installation.
+* **Version Control:** you must ensure continuous control of the simulator. When do you need to update it? Can the update be automated for all users? Can you use different versions of the simulator at the same time?
+* **Stability:** will the simulator be stable or do you need to restart it often?
+* **Cost:** do you have to buy a license for every instance of the simulator or for every user?
+
+With ActorJs, everything will be integrated. Everything is stored in [[REF=, ABS_Repo]]s. When an update is completed, just push it to the repo, and it is available for everyone else.
+
+In addition, it is unlikely that a simulator can help you with these issues:
+* **New functions:** the simulator must be updated every time you need it to support new functions. This can be time-consuming and costly, and it can limit your flexibility.
+* **Configuration:** it will probably be difficult to control the simulator from the [[REF=, ABS_Test_Case]]s.
+* **Negative Testing:** most simulators will not allow you to do all the negative testing you need.
+* **Timing:** most simulators will have problems with simulating timing problems.
+
+With ActorJs, all these problems are very easy to solve. You have full control of all code. You implement [[REF=, ABS_Actor_State_Execution]] in the [[REF=, ABS_Actor]]s. And [[REF=, ABS_Test_Case]]s are 100 % data driven. A [[REF=, ABS_Test_Case]] chooses which [[REF=, ABS_Actor]]s to use and provides them with [[REF=, ABS_Test_Data]].
+
+**`Conclusion: ActorJs is the clear winner over simulators!`**
+
+[[ANCHOR={"id":"703f131c-868b-4dba-ae85-5ceb7af4552a","visible":true}]]
+[[NOTE={"guid":"9f5bb34d-ebab-4949-9589-32c1329ab69a"}]]
+### **Mocked-up processes create a lot of extra work**
+Mocked-up processes create a lot of problems that must be solved before the real testing can start:
+1) Start and Stop: these processes must be started and stopped. Will that be up to the test case, the test suite or a framework?
+2) If these processes crash, who will do the diagnostics and solve the problem?
+3) These processes need test data and addresses; who will give them this information?
+4) Will they do verification?
+5) Will they be reusable?
+
+You will probably have to build your own test framwork.
+
+**`Conclusion: ActorJs easily surpasses mocked-up systems!`**
+
+[[ANCHOR={"id":"0f71bddf-3839-40bf-9501-50881293629d","visible":true}]]
+[[NOTE={"guid":"3ab615c4-45a3-49f8-bf43-69cdac81c0df"}]]
+### **Real systems limit creativity**
+Real systems present the same problems as simulators, but it is likely that they will be even more limited -- they probably do not have any remote control interfaces to control them.
+
+**`Conclusion: In the development phase, ActorJs beats real systems, hands down!`**. 
+
+<br/>
+<br/>
+<br/>
+<br/>
+

package/Documentation/Document-global-why-actors-unlimited.txt

@@ -0,0 +1,182 @@
+# Why ActorJs?
+
+[[EMBED=a/a]]
+[[NOTE={"guid":"4260461c-24b1-449e-b4dc-214ed848f61d"}]]
+
+[ssssssssssssssssssss](#e8ed4041-576c-4a7c-b319-3e1087a17d7c)
+
+[[ANCHOR={"id":"f549215f-aa53-4ad9-872c-55ba070208a2","visible":true}]]
+[[NOTE={"guid":"58327f38-8f06-428a-9f41-1dbb6a331913"}]]
+
+## ActorJs is a javascript tool to build complex Test Cases and Load Cases
+ActorJs is a tool to isolate a [System Under Test](system-under-tests). It supports unlimited number of actors working in a multi-threaded way. This makes it possible to isolate the [System Under Test](system-under-tests) in a very easy way independent on the number of protocols used by the System Under Test.
+
+An [Actor](actors) is a piece of code that the [Test Case Execution Engine](test-case-execution-engine) executes in parallel or serial with other Actors dependent on the [Test Data](test-datas) of the [Test Case](test-cases). The Actors will be reused in a lot of Test Cases. They will be reused both in:
+* **[Function Test](functions-tests)**
+* **[Load Test](load-tests)**
+
+[[NOTE={"guid":"1ae50f7f-90c8-4779-9d97-59e20e799d94"}]]
+
+### Simulators are very complex to use and hard to automate
+When using simulators you add a lot of complexity to your environment. The simulator must be part of your environment and be totally integrated in you environment. Task that have to be solved:
+* **Environment:** the simulator must be part of your environment. When setting up a new lab the simulator must automatically be installed and configured.
+* **Version Control:** you must have control of the simulator. When do you need to update the simulator? Can the update be automated for all users?
+* **Stability:** will the simulator be stable or do you need to restart it a lot of times?
+
+With ActorJs every thing will be integrated. Every thing is stored in a source control repo. When a update is dome just push it to the repo, then it is available for everyone else.
+
+There are a lot of issues that the simulator probably cannot help you with:
+* **New functions:** the simulator must be updated every time you need it to support new functions. It can take a lot of time and cost a lot and it might limit you.
+* **Configuration:** it will probably be hard to control the simulator from the Test Case.
+* **Negative Testing:** most simulators will not allow you to do all negative testing you need.
+* **Timing:** most simulators will have problems to simulate timing problems.
+
+With ActorJs all these issues are very easy to solve. You have full control of all code. You will write Actors. Still Test Cases are 100% data driven. A Test Case chooses which Actors to use and provides them with Test Data.
+
+**Conclusion: DO NOT USE SIMULATORS**
+
+[[NOTE={"guid":"a9183201-58e4-413b-8ce5-558c64df53a1"}]]
+## Analyze to show the benefits with ActorJs
+
+[[NOTE={"guid":"bef4c7c1-2142-4105-9ab1-87c138e231d7"}]]
+### Step 1 - Web Server as SUT
+Easy to test, just get the site and verify that it is ok.```seq
+Nodes[browser, SUT]
+browser => SUT[http]: GET /www.site.com HTTP 1.1
+SUT => browser[http]: 200 Ok
+```
+Here is the implementation of the *run* state of the **browser**. The Actor type is [ActorOriginating](actor-originating).
+
+```javascript
+
+
+
+*run() {
+  this.httpConnection.send(new HttpGetSiteRequest());
+  let response = yield this.httpConnection.receive();
+  VERIFY_VALUE(200, response.getStatusCode());
+}
+
+```
+
+[[NOTE={"guid":"b0f1871d-8a4c-4dfe-b12d-5e6be15fb828"}]]
+### Step 2 - Web Server depending on a database as SUT
+Web servers usually depends on a database. The database will at least contain:
+* configuration data
+* business data```seq
+Nodes[browser, SUT, DB]
+browser => SUT[http]: GET /www.site.com HTTP 1.1
+SUT <-> DB[sql]: configuration data
+SUT <-> DB[sql]: business data
+SUT => browser[http]: 200 Ok
+```
+
+The Database is most often to be seen as being a part of the SUT and therefor we have to update the configuration data and/or the business data to be able to test the SUT.
+
+```seq
+Nodes[Condition, browser, SUT, DB]
+Condition => DB[sql]: new config values
+DB => Condition[sql]: previus config values
+browser => SUT[http]: GET /www.site.com HTTP 1.1
+SUT <-> DB[sql]: configuration data
+SUT <-> DB[sql]: business data
+SUT => browser[http]: 200 Ok
+Condition => DB[sql]: config restore
+DB => Condition[sql]: 
+```
+
+Here is the implementation of the *runPre* state of the **Condition**. The Actor type is [ActorCondition](actor-condition). The Actor must store the previous values so it can be restored in the end of the Test Case.
+
+```javascript
+
+
+
+
+
+*runPre() {
+  this.sqlConnection.send(new SqlQueryMessage(this.newValues));
+  let response = yield this.sqlConnection.receive();
+  VERIFY_VALUE('success', response.getResult());
+  this.previusValues = response.getValues();
+}
+```
+
+Here is the implementation of the *runPost* state of the **Condition**. The Actor type is [ActorCondition](actor-condition). The Actor will restore the database with its previous values.
+
+```javascript
+
+
+
+
+
+*runPost() {
+  this.sqlConnection.send(new SqlQueryMessage(this.previusValues));
+  let response = yield this.sqlConnection.receive();
+  VERIFY_VALUE('success', response.getResult());
+}
+```
+
+[[NOTE={"guid":"1a04f41c-8809-493f-b62f-a6687bc620e3"}]]
+### Step 3 - Proxy as SUT for a web Server
+When testing a proxy we also need to have terminating Actors to avoid simulators.```seq
+Nodes[Condition, browser, SUT, DB, Webserver]
+Condition => DB[sql]: new config values
+DB => Condition[sql]: previus config values
+browser => SUT[http]: GET /www.site.com HTTP 1.1
+SUT -> DB[sql]: data 1
+SUT -> DB[sql]: data n
+SUT => Webserver[http]: GET /www.site.com HTTP 1.1
+Webserver => SUT[http]: 200 Ok
+SUT => browser[http]: 200 Ok
+Condition => DB[sql]: config restore
+DB => Condition[sql]: 
+```
+
+Here is the implementation of the *run* state of the **Webserver**. The Actor type is [ActorTerminating](actor-terminating).
+
+```javascript
+
+
+
+
+
+*run() {
+  yield this.httpConnection.accept();
+  let request = yield this.httpConnection.receive();
+  this.httpConnection.send(new HttpOkResponse(Http.OK));
+}
+```
+
+```seq
+Nodes[CONDITION, browser, SUT, DB, HSS, Ext_Service]
+CONDITION => DB[sql]: config set
+browser => SUT[http]: GET /www.site.com HTTP 1.1
+SUT -> DB[sql]: data 1
+SUT -> DB[sql]: data n
+SUT => HSS[diameter]: Cx
+HSS => SUT[diameter]: 
+SUT => Ext_Service[http]: GET /data HTTP 1.1
+Ext_Service => SUT[http]: 200 Ok
+SUT => browser[http]: 200 Ok
+CONDITION => DB[sql]: config restore
+```
+
+```seq
+Nodes[CONDITION, browser, SUT, DB, HSS, Ext_Service, Ext_Service_2]
+CONDITION => DB[sql]: config set
+browser => SUT[http]: GET /www.site.com HTTP 1.1
+SUT -> DB[sql]: data 1
+SUT -> DB[sql]: data n
+SUT => HSS[diameter]: Cx
+HSS => SUT[diameter]: 
+SUT => Ext_Service[http]: GET /data HTTP 1.1
+Ext_Service => SUT[http]: 500 Internal Server Error
+SUT => Ext_Service_2[http]: GET /data HTTP 1.1
+Ext_Service_2 => SUT[http]: 200 Ok
+SUT => browser[http]: 200 Ok
+CONDITION => DB[sql]: config restore
+```
+
+[[ANCHOR={"id":"e8ed4041-576c-4a7c-b319-3e1087a17d7c","visible":true}]]
+[[NOTE={"guid":"9a75e7ae-fe5e-4da2-b774-9f857ec494cb"}]]
+### Common Test Tools are too limited

package/Documentation/Document-global-x-test-case-tool.txt

@@ -0,0 +1,2 @@
+# NEW DOCUMENT
+## Please Edit: ***`TO BE DONE !!!`***