[GitHub] [skywalking-website] CrocoRyan commented on a change in pull request #172: blog: add the design doc of NGE2E

[GitBox <gi...@apache.org>]

CrocoRyan commented on a change in pull request #172:
URL: https://github.com/apache/skywalking-website/pull/172#discussion_r545633863



##########
File path: content/blog/e2e-design/index.md
##########
@@ -0,0 +1,276 @@
+---
+title: "[Design] NGE2E - Next Generation End-to-End Testing Framework"
+date: 2020-12-14
+author: "[Zhenxu Ke](https://github.com/kezhenxu94), Tetrate.io; [Huaxi Jiang](http://github.com/fgksgf), Committer; [Ke Zhang](http://github.com/HumbertZhang), Committer"
+description: "The design of Next Generation End-to-End Testing Framework"
+---
+
+NGE2E is the next generation End-to-End Testing framework that aims to help developers to set up, debug, and verify E2E tests with ease. It's built based on the lessons learnt from tens of hundreds of test cases in the SkyWalking main repo.
+
+# Goal
+
+- keep the feature parity with the existing E2E framework in SkyWalking main repo;
+- support both [docker-compose](https://docs.docker.com/compose/) and [KinD](https://kind.sigs.k8s.io) to orchestrate the tested services under different environments;
+- get rid of the heavy `Java/Maven` stack, which exists in the current E2E; be language independent as much as possible, users only need to configure YAMLs and run commands, without writing codes;
+
+# Non-Goal
+
+- this framework is not involved with the build process, i.e. it won't do something like `mvn package` or `docker build`, the artifacts (`.tar`, docker images) should be ready in an earlier process before this;
+- this project doesn't take the plugin tests into account, at least for now;
+- this project doesn't mean to add/remove any new/existing test case to/from the main repo;
+- this documentation won't cover too much technical details of how to implement the framework, that should go into an individual documentation;
+
+# Design
+
+Before diving into the design details, let's take a quick look at how the end user might use NGE2E.
+
+> All the following commands are mock, and are open to debate.
+
+To run a test case in a directory `/path/to/the/case/directory`
+
+```shell
+swctl e2e run /path/to/the/case/directory
+
+# or
+
+cd /path/to/the/case/directory && swctl e2e run
+```
+
+This will run the test case in the specified directory, this command is a wrapper that glues all the following commands, which can be executed separately, for example, to debug the case:
+
+**NOTE**: because all the options can be loaded from a configuration file, so as long as a configuration file (say `e2e.yaml`) is given in the directory, every command should be able to run in bare mode (without any option explicitly specified in the command line);
+
+### Set Up Services
+
+```shell
+swctl e2e setup --env=compose --file=docker-compose.yaml --wait=for=service-health
+swctl e2e setup --env=kind --file=kind.yaml --resources=bookinfo.yaml,gateway.yaml --wait=for=pod-ready
+swctl e2e setup # If configuration file e2e.yaml is present
+```
+    
+- `--env`: the environment, may be `compose` or `kind`, represents docker-compose and KinD respectively;
+- `--file`: the `docker-compose.yaml` or `kind.yaml` file that declares how to set up the environment;
+- `--resources`: for KinD, the resources files/directories to apply (using `kubectl apply -f`);
+- `--command`: a command to run after the environment is started, this may be useful when users need to install some extra tools or apply resources from command line, like `istioctl install --profile=demo`;
+- `--wait`: wait until the given condition is met; the most frequently-used strategy should be `for=service-health`, that makes the `e2e setup` command to wait for all services to be `healthy`; other possible strategies may be something like `for="log:Started Successfully"`, `for="http:localhost:8080/healthcheck"`, etc. if really needed;
+
+
+### Trigger Inputs
+
+```shell
+swctl e2e trigger --interval=3s --times=0 --action=http --url="localhost:8080/users"
+swctl e2e trigger --interval=3s --times=0 --action=cmd --cmd="curl localhost:8080/users"
+swctl e2e trigger # If configuration file e2e.yaml is present
+```
+
+- `--interval=3s`: trigger the action every 3 seconds;
+- `--times=0`: how many times to trigger the action, `0=infinite`;
+- `--action=http`: the action of the trigger, i.e. "perform an http request as an input";
+- `--action=cmd`: the action of the trigger, i.e. "execute the `cmd` as an input";
+
+
+### Query Output
+
+```shell
+swctl service ls
+```
+
+this does exactly the same as what `swctl` is doing at present;
+
+
+### Verify
+
+```shell
+swctl e2e verify --actual=actual.data.yaml --expected=expected.data.yaml
+swctl e2e verify --query="service ls" --expected=expected.data.yaml
+swctl e2e verify # If configuration file e2e.yaml is present
+```
+
+- `--actual`: the actual data file;
+- `--expected`: the expected data file;
+- `--query`: the query to get the actual data, will be executed in command `swctl`;
+  > the `--query` option will get the output into a temporary file and use the `--actual` under the hood;
+
+
+### Cleanup
+
+This step is automatically done by the framework according to the setup step.
+
+### Summarize
+
+To summarize, the directory structure of a test case might be
+
+```text
+case-name
+├── agent-service        # optional, an arbitrary project that is used in the docker-compose.yaml if needed
+│   ├── Dockerfile
+│   ├── pom.xml
+│   └── src
+├── docker-compose.yaml
+├── e2e.yaml             # see a sample below
+└── testdata
+    ├── expected.endpoints.service1.yaml
+    ├── expected.endpoints.service2.yaml
+    └── expected.services.yaml
+```
+
+or
+
+```text
+case-name
+├── kind.yaml
+├── bookinfo
+│   ├── bookinfo.yaml
+│   └── bookinfo-gateway.yaml
+├── e2e.yaml             # see a sample below
+└── testdata
+    ├── expected.endpoints.service1.yaml
+    ├── expected.endpoints.service2.yaml
+    └── expected.services.yaml
+```
+
+a sample of `e2e.yaml` may be
+
+```yaml
+setup:
+  env: kind
+  file: kind.yaml
+  resources: bookinfo.yaml
+  command: | # it can be a shell script or anything executable
+    istioctl install --profile=demo -y
+    kubectl label namespace default istio-injection=enabled
+
+  # OR
+  # env: compose
+  # file: docker-compose.yaml
+
+  wait: 
+    for: service-health

Review comment:
       I have questions about the "wait" segment:
   Are we able to merge those wait step into one independent block , if there're multiple prerequisites to start the test?
   Plus, the "for" syntax seems to be a little bit ambiguous since many of users initially recognize this as some sort of iteration thing




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org