feat(examples): Add expected CLI output for given inputs

Author: matevz

.github/workflows/ci-tests.yml

@@ -43,3 +43,8 @@ jobs:
       - name: Run tests
         run: |
           make test
+      - name: Check examples
+        run: |
+          make clean-examples
+          make examples
+          git diff --exit-code examples

Makefile

@@ -1,5 +1,8 @@
 include common.mk
 
+# Each Oasis CLI example's input .in must have a corresponding output .out.
+EXAMPLES := $(patsubst %.in,%.out,$(wildcard examples/*/*.in))
+
 # Check if Go's linkers flags are set in common.mk and add them as extra flags.
 ifneq ($(GOLDFLAGS),)
 	GO_EXTRA_FLAGS += -ldflags $(GOLDFLAGS)
@@ -9,10 +12,20 @@ endif
 all: build
 
 # Build.
-build:
+build: oasis
+oasis: $(shell find . -name "*.go" -type f) go.sum go.mod
 	@$(PRINT) "$(MAGENTA)*** Building Go code...$(OFF)\n"
 	@$(GO) build -v -o oasis $(GOFLAGS) $(GO_EXTRA_FLAGS)
 
+examples: $(EXAMPLES)
+
+examples/%.out: examples/%.in oasis scripts/gen_example.sh
+	@rm -f $@
+	@scripts/gen_example.sh $< $@
+
+clean-examples:
+	@rm -f examples/*/*.out
+
 # Format code.
 fmt:
 	@$(PRINT) "$(CYAN)*** Running Go formatters...$(OFF)\n"
@@ -64,6 +77,8 @@ clean:
 # List of targets that are not actual files.
 .PHONY: \
 	all build \
+	examples \
+	clean-examples \
 	fmt \
 	$(lint-targets) lint \
 	$(test-targets) test \

examples/README.md

@@ -0,0 +1,78 @@
+# Oasis CLI Examples
+
+This folder contains example scenarios for the Oasis CLI. The snippets are
+included in the documentation and also serve as a check for potential
+regressions in the CLI.
+
+Each example is stored inside its own folder. The folder contains:
+
+- one or more invocation files,
+- output file for each invocation file with the content of the resulting
+  standard output,
+- input and output artifacts
+- `config` folder containing custom config file to be used for the scenario.
+
+## Invocation files
+
+Invocation files have `.in` extension and they will be executed in
+alphabetic order. This is important, if you have destructive operations (e.g
+adding or removing a wallet) where the order of execution should be respected.
+In this case, name the files starting with a number, for example `00-create.in`.
+
+Each `.in` file begins with `oasis` command, which will be replaced with the
+path to the actual Oasis CLI command when generating example outputs.
+
+An example invocation file content to create a new wallet:
+
+```
+oasis wallet create john
+```
+
+### Non-Interactive Execution
+
+If you want to invoke Oasis in a non-interactive mode (by appending
+`-y -o /dev/null` parameters), name the invocation file by appending `.y` after
+the `NUMBER`. For example `00.in` becomes `00.y.in`.
+
+### Custom Config Files
+
+Sometimes, you want to use a predefined config file for the Oasis CLI. Put
+your desired Oasis CLI config folder inside the `config` subfolder inside the
+example folder. Upon example invocation, the folder will be copied over to a
+temporary location and provided to CLI with `--config` parameter. Then, the
+example will be invoked beginning with the provided config file. This way, you
+can prepare and execute specific CLI scenarios without a dozen of presteps.
+
+### Example Artifacts
+
+If an example requires external files such as a JSON file containing an entity
+descriptor or a raw transaction, simply put it alongside the input file.
+Assume the working directory will be the one that the input file resides in.
+The same goes for the output artifacts (e.g. signed transaction).
+
+## Output Files
+
+The Oasis CLI output for the given input will be stored in a file named the same
+as the corresponding invocation file, but having `.out` extension instead of
+`.in`.
+
+Scenarios should be designed in a way that the output files remain equal unless
+a different behavior of the Oasis CLI is expected.
+
+## Static examples
+
+If you do not want the example to be executed, but you simply want to store
+Oasis CLI execution snippets for example to be included in the documentation,
+append `.static` to the corresponding `.in` and `.out` files. Such files will
+not be tested and regenerated each time, but you will have to update it
+manually. We discourage using this mechanism, but it may be useful in cases when
+the output is expected to change and would not make sense to update it each time
+(e.g. `oasis network status` returns the current block height).
+
+## Running Examples
+
+To run the examples and generate outputs, invoke in the top-level directory:
+
+```sh
+make examples
+```

examples/account/allow-negative.in.static

@@ -0,0 +1 @@
+oasis account allow logan -- -10

examples/account/allow-negative.out.static

@@ -0,0 +1,14 @@
+You are about to sign the following transaction:
+Method: staking.Allow
+Body:
+  Beneficiary:   oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl
+  Amount change: -10.0 TEST
+Nonce:  0
+Fee:
+  Amount: 0.0 TEST
+  Gas limit: 1288
+  (gas price: 0.0 TEST per gas unit)
+
+Network:  testnet
+ParaTime: none (consensus layer)
+Account:  oscar

examples/account/allow-paratime.y.in

@@ -0,0 +1 @@
+oasis account allow paratime:sapphire 10

examples/account/allow-paratime.y.out

@@ -0,0 +1,14 @@
+You are about to sign the following transaction:
+Method: staking.Allow
+Body:
+  Beneficiary:   oasis1qqczuf3x6glkgjuf0xgtcpjjw95r3crf7y2323xd
+  Amount change: +10.0 TEST
+Nonce:  1
+Fee:
+  Amount: 0.0 TEST
+  Gas limit: 1278
+  (gas price: 0.0 TEST per gas unit)
+
+Network:  testnet
+ParaTime: none (consensus layer)
+Account:  oscar

examples/account/allow.y.in

@@ -0,0 +1 @@
+oasis account allow logan 10

examples/account/allow.y.out

@@ -0,0 +1,14 @@
+You are about to sign the following transaction:
+Method: staking.Allow
+Body:
+  Beneficiary:   oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl
+  Amount change: +10.0 TEST
+Nonce:  1
+Fee:
+  Amount: 0.0 TEST
+  Gas limit: 1278
+  (gas price: 0.0 TEST per gas unit)
+
+Network:  testnet
+ParaTime: none (consensus layer)
+Account:  oscar

examples/account/amend-commission-schedule.y.in

@@ -0,0 +1 @@
+oasis account amend-commission-schedule --bounds 29000/1000/2000,35000/900/1900 --rates 29000/1500