Merge pull request #838 from openBackhaul/develop

To Tag Version 2.0.1_impl and 2.0.1_test

.github/workflows/test-ap-pr.yml

@@ -0,0 +1,28 @@
+name: Run Jest tests in server/applicationPattern
+
+on:
+  pull_request:
+    branches:
+      - develop
+
+jobs:
+  test:
+    name: Run Jest tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: 16
+
+      - name: Install dependencies
+        run: npm install
+        working-directory: server/applicationPattern
+
+      - name: Run Jest tests
+        run: npm test
+        working-directory: server/applicationPattern

doc/ElementsApplicationPattern/ElementsApplicationPattern.md

@@ -4,10 +4,11 @@
 ### Concepts
 
 **General Design Principles**
-- [API-First Approach](./Principles/ApiFirst/ApiFirst.md)
-- [RESTful](./Principles/Restful/Restful.md)
 - [Microservice](./Principles/Microservice/Microservice.md)
-- [CONFIGfile](./Principles/ConfigFile/ConfigFile.md)
+- [HTTP Request](./Principles/Http/Http.md)
+- [RESTful](./Principles/Restful/Restful.md)
+- [API-First Approach](./Principles/ApiFirst/ApiFirst.md)
+- [OpenAPI Specificatgion](./Principles/OpenApiSpecification/OpenApiSpecification.md)
 
 **Functions**
 - [Structure of Services](./Functions/StructureOfServices/StructureOfServices.md)
@@ -16,35 +17,30 @@
 - [Structure of Internal Forwarding](./Functions/StructureOfInternalForwarding/StructureOfInternalForwarding.md)
 - [Types of Internal Forwarding](./Functions/TypesOfInternalForwardings/TypesOfInternalForwardings.md)
 - [Substructure of Management of Internal Forwarding](./Functions/SubstructureOfManagementOfInternalForwardings/SubstructureOfManagementOfInternalForwardings.md)
-- [Concept of _CONFIGfile_](./Functions/ConceptOfConfigFile/ConceptOfConfigFile.md)
-- [Structure of _CONFIGfile_](./Functions/StructureOfConfigFile/StructureOfConfigFile.md)
-- [Concept of OpenApiSpecification](./Functions/ConceptOfOas/ConceptOfOas.md)
-- [Structure of OpenApiSpecification](./Functions/StructureOfOas/StructureOfOas.md)
-- [Concept of TestCases](./Functions/ConceptOfTestCases/ConceptOfTestCases.md)
-- [Structure of TestCases](./Functions/StructureOfTestCases/StructureOfTestCases.md)
+- [Concept of CONFIGfile](./Functions/ConceptOfConfigFile/ConceptOfConfigFile.md)
+- [Concept of DATAfile](./Functions/ConceptOfDataFile/ConceptOfDataFile.md)
+- [Structure of CONFIGfile](./Functions/StructureOfConfigFile/StructureOfConfigFile.md)
+- [Concept of Test Case Collection](./Functions/ConceptOfTestCaseCollection/ConceptOfTestCaseCollection.md)
+- [Structure of Test Case Collection](./Functions/StructureOfTestCaseCollection/StructureOfTestCaseCollection.md)
+- [Structure of Test Case](./Functions/StructureOfTestCase/StructureOfTestCase.md)
 
 **Names and IDs**
 - [Structure of ApplicationNames](./Names/StructureOfApplicationNames/StructureOfApplicationNames.md)
 - [Structure of ServiceNames](./Names/StructureOfServiceNames/StructureOfServiceNames.md)
 - [Structure of Release Numbers](./Names/StructureOfReleaseNumbers/StructureOfReleaseNumbers.md)
 - [Structure of UUIDs](./Names/StructureOfUuids/StructureOfUuids.md)
 - [Structure of Internal Forwarding Names](./Names/StructureOfInternalForwardingNames/StructureOfInternalForwardingNames.md)
+- [Structure of OaM paths](./Names/StructureOfOamPaths/StructureOfOamPaths.md)
 
 
 ### Underlying Information Model
 
-**Overview Information Model**
-
 **Classes**
 - [ControlConstruct](./InformationModel/ControlConstruct/ControlConstruct.md) 
-- [LogicalTerminationPoint](./InformationModel/LogicalTerminationPoint/LogicalTerminationPoint.md)
-- LayerProtocol
-- Profile
-- **ForwardingDomain**: The ForwardingDomain(FD) aggregates one or more ForrwardingConstruct(FC). Theoretically CC consists of a list of FDs. But practically a Microservice consists of a single FD instance. FDs are identified by a uuid.
-- [ForwardingConstruct](./InformationModel/ForwardingConstruct/ForwardingConstruct.md)
-- ForwardingConstructPort
-- NetworkControlDomain
-- Link
+- [LogicalTerminationPoint and LayerProtocol](./InformationModel/LogicalTerminationPoint/LogicalTerminationPoint.md)
+- [ForwardingDomain, ForwardingConstruct and ForwardingConstructPort](./InformationModel/ForwardingConstruct/ForwardingConstruct.md) 
+- [ProfileCollection and Profile](./InformationModel/Profile/Profile.md) 
+- [NetworkControlDomain and Link](./InformationModel/Link/Link.md) 
 
 
 ### Basic Services

doc/ElementsApplicationPattern/Functions/ConceptOfConfigFile/ConceptOfConfigFile.md

@@ -0,0 +1,43 @@
+# Concept of the CONFIGfile
+
+### Background and main purpose of the CONFIGfile
+There are numerous communication relationships between applications, due to
+-	functions being distributed across many individual applications in a modular application layer
+-	and applications consuming functions provided by other applications.  
+
+These communication relationships are directed, meaning that a client is sending requests to a server. For actually reaching the server, the client must correctly addess these requests.
+
+However, the server's address may change.  
+For example, a non-backward compatible modification to a function (e.g. a bug fix) would require changing the version number in the URI for calling this function. If address information were hardcoded into the client, the client's program code would require an update in such cases.  
+Consequently, a change to an application would require changes to other applications.  
+Such propagating need for adaptation would make simple adjustments very cumbersome; and the architecture would be rigid against further development.  
+Therefore, address information needs to be configurable in some way and it needs to be saved independently from the program code.  
+This is the main purpose of the CONFIGfile.  
+
+**Content: address information and parameter values**  
+The CONFIGfile does not just store address information, but also all kinds of parameter values.  
+Parameters might be required for e.g., formulas, algorithms, or processes that are executed inside the application.  
+Such parameters are usually of primitive data types like Integer or String.  
+
+**Not part of the content: Application Data**
+- Some applications build their own data during runtime. Such data would be called ApplicationData.
+- Example: the ExecutionAndTraceLog is creating a record for every request executed in the application layer..
+- The CONFIGfile shall not contain ApplicationData, but it might contain information that is required for connecting a separate file or database that is holding the ApplicationData.  
+
+### CONFIGfile
+Immediately after launching, the application is reading the CONFIGfile.
+Consequently, the values that are defined in the CONFIGfile represent the initial state of the application.  
+
+_ConfigFile changes_  
+The CONFIGfile is written in JSON format to support being read by JavaScript based applications (note that it could also be handled by any other programming language like e.g. Java, Python or PHP).
+It could be manually altered if required but operating the updated configuration would require restarting the application.
+The applications, which are based on the MW SDN ApplicationPattern, are supporting changing their configuration via the REST API during runtime.
+These changes are then automatically written into the CONFIGfile.  
+
+_Storage_  
+The CONFIGfile is stored separately from the code of the application.
+So, in case of failure, a new instance of an application could be started with the exact latest configuration of a broken instance.
+For completeness, it should be noted that all applications of the MW SDN application layer are stateful due to their configurability.
+That state might change over the course of their operation, and it must be kept consistent.
+This characteristic makes integration with Kubernetes a bit more complex.
+

doc/ElementsApplicationPattern/Functions/ConceptOfDataFile/ConceptOfDataFile.md

@@ -0,0 +1,7 @@
+# Concept of the DATAfile
+
+Applications need an initial state during testing, too.  
+Loading this initial state of an application under test into the request collection that is implementing the test cases supports assessing the answers provided by the REST API.  
+
+For the sake of simplicity, the DATAfile includes the configuration of the application under test in the exact same format as the CONFIGfile.  
+However, the DATAfile includes some additional information that the request collection requires to address the application under test.  

doc/ElementsApplicationPattern/Functions/ConceptOfTestCaseCollection/ConceptOfTestCaseCollection.md

@@ -0,0 +1,133 @@
+# Concept of the Test Case Collection
+
+### Purposes of Test Case Collection
+
+**Definition of the Business Logic**  
+The Test Case Collection (TCC) is an important part of the specification of an application.  
+While the OAS defines the interface of the application and the CONFIGfile describes its initial data, the TCC is for specifying the logic that happens inside the application.  
+
+Example: Suppose the purpose of the application is to calculate the current capacity of a microwave link:  
+- The OAS would define the identifier that is needed to select the microwave link and the format of the result.  
+- The CONFIGfile would hold constant parameters that are needed in the equation and describe the requests that need to be made to the device to get the variable input parameters. 
+- Some test case from the collection needs to implement the concrete formula for calculating the reference value in evaluating the application's response.    
+
+**Acceptance Testing**  
+Code developed on the basis of an "MS Word" specification must be tested manually by the person who wrote the specification.  
+This often leads to discussions about how to interpret the words in the specification.    
+After going through this process several times, a kind of iterative approach becomes established.  
+Since the functional scope is not conclusively defined at the beginning, the implementation effort cannot be determined before completion.  
+
+The MW SDN approach involves multiple software providers estimating their costs of an implementation.  
+Just one gets assigned the task also based on its estimate.  
+Potential suppliers need to know the criteria that will ultimately lead to successful acceptance in order to realistically calculate their efforts.  
+Therefore, the acceptance tests must already be part of the specification.  
+With this approach, the ApplicationOwner can expect to be supplied with code that will 100% successfully pass acceptance testing.  
+The iterative process during the acceptance phase is eliminated.  
+
+**CI/CD**  
+It is expected that applications will build upon each other.  
+For example, application B will consume services provided by application A.  
+However, it must be possible to make changes to application A in order to dynamically update and extend the functionality of the application layer in the long term.  
+Of course, it must be ensured that application B still functions properly after application A has been changed.  
+This means that a change to application A is accompanied by a test of application B.  
+
+The number of applications may grow dynamically.  
+The dependencies between the individual applications may not always be obvious.  
+Therefore, all applications need to be retested whenever one of them is changed (integration testing).  
+Of course, this is only possible with automation.  
+This means that a complete Test Case Collection for each application is a prerequisite for the long-term development of the application layer.  
+
+### Kinds of tests to be covered  
+
+**Testing the API**  
+The OAS defines paths, bodies and headers.  
+Testing must ensure that  
+- specified paths are actually implemented  
+- ResponseBodies have the specified structure  
+- RequestBodies that do not comply with the prescribed structure get objected  
+- datatypes are kept and checked  
+- string patterns and integer boundaries are checked  
+- response headers are comprising the expected values  
+- and much more  
+
+These are routine tests that are required to ensure the quality of the data within the application under test and its good behavior towards consuming applications.  
+These tests do not provide any information beyond the AOS.  
+Basically, they could be derived automatically from the AOS.  
+
+**Testing the Business Logic**  
+Each application is expected to add some functionality to the application layer.  
+This functionality could be  
+- repeated execution of an activity according to a generic set of rules  
+- aggregation of information according to a specific pattern  
+- calculation of a derived value according to a certain formula  
+- etc.  
+
+This functionality is the purpose of the application, but it is not defined in the OAS or in the CONFIGfile.  
+The test cases for validating the business logic must actually describe the business logic.  
+A test case validating the repeated execution of an activity would be expected to contain a number of 'if-then-else' decisions or 'for' loops to describe the generic rule set.  
+A test case for validating a formula would therefore contain exactly this formula and thus create the reference values for checking the result values of the application with it.  
+A list of example input and output values would not be sufficient.  
+Depending on the individual case, it must be considered whether randomly generated input values are sufficient, or whether the correct retrieval of input values from external sources (e.g. microwave devices) must also be checked in the test case.  
+
+It is highly advisable to be as clear and precise as possible both in the description of the input values and in the description of the rules and formulas.  
+If necessary, the test case code for validating the business logic could also be included in the application's self-documentation via additional fields.
+
+**Testing the Interaction with surrounding Applications (System Testing)**  
+Even in the case that both application A and application B, operated on their own, provide completely flawless and logical results, it is not guaranteed that the parallel operation of application A and application B will also provide flawless and logical results in all situations.  
+The resulting mutual dependencies between the algorithms represent the greatest long-term risk to stable and error-free operation of a modular automation platform.  
+Clear and complete descriptions of the functioning of each component and testing the mutual influences as completely as possible are probably the most effective means of maintaining control.  
+
+Easy example: Once an application has processed a request, it should send a record to the ExecutionAndTraceLog application.  
+A complete TCC must include a test case that verifies in the ExecutionAndTraceLog application that this record has not only arrived, but that it contains all the expected values correctly.  
+This test comes as part of the ApplicationPattern.  
+
+More individual example: Suppose an application contains a formula that includes several externally retrieved values.  
+Also, suppose that obtaining one of the external values suddenly fails.  
+Would the application then calculate the requested result based on the available values, or would it stop calculating and report an error?  
+Obviously, one of the two variants leads to funny system behavior, which keeps any number of colleagues busy with a cheerful search for a sporadically occurring error of completely untransparent root cause.  
+
+Formulating these test cases requires a lot of experience and is also very individual for the respective application.  
+
+**Stability testing**  
+Even though the MW SDN application layer is very modular, the individual components are highly interdependent.  
+This means that the failure of an application can result in a very far-reaching loss of function.  
+
+Examples of possible causes of an application becoming unstable:  
+- An application contains a fraction and a variable parameter might cause the denominator to equal zero  
+- Some external condition may cause the application to repeat some activity for an infinite number of times  
+- An aborted upgrade process could leave surrounding applications in an undefined state  
+- Applications (e.g. of the TinyApplicationController) could collapse under a flood of requests when the entire application layer is restarted  
+- etc.  
+
+Formulating tests to rule out unstability requires creativity and experience, since stability is usually compromised in unexpected boundary or special cases.  
+
+**Testing compliance with rules of good conduct**  
+The TCC should also be used to exclude implementation variants that tend to be harmful to the system.  
+For example, unnecessarily high loads on the controller or even on the devices in the transport network must be excluded.  
+
+The experience with undesired behavior of applications will certainly become more extensive in the future.  
+
+### Sharing the load  
+
+Because of the diversity of knowledge and experience, it seems reasonable to assemble the TCC from test cases provided by various supporters.  
+Test case delivery is distributed across the following roles:    
+
+| Kind of test case | ApplicationOwner | TestingExpert | IT Expert |
+|-|-|-|-|
+| Business Logic | Responsible | Consulted | |
+| System | Consulted | Responsible 1) | Consulted 1) |
+| Good Conduct | | Consulted | Responsible |
+| Stability | | Consulted | Responsible |
+| API | | | Responsible |
+
+1\) IT Experts responsible in the beginning. TestingExpert needs to grow into responsible role.  
+
+The ApplicationOwner is responsible for ensuring that a complete TCC is eventually passed to the ApplicationImplementers.
+
+### InterfaceValidator  
+
+Originally, the InterfaceValidator was used to test that the vendors' implementations of the ONF TR-532 definitions are working as expected.  
+It is a kind of framework that provides not only a structure but also basic functionality for incorporating an increasing variety of test cases.  
+Initially, the InterfaceValidator was written and operated in the Postman GUI.  
+As part of the continuous integration of applications, it was decided to export the finished TCC from Postman and run it automatically through Jenkins in the text-based Newman.  
+Writing test cases in Postman is supported by mock servers that can be created from the API definitions to be tested.