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

.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,79 @@
+# 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), replace the `.in` extension with `.y.in`. For
+example `00-create.in` becomes `00-create.y.in`.
+
+### Custom Config Files
+
+Sometimes, you want to use a predefined config file for the Oasis CLI. Put
+your desired `cli.toml` and the wallet files to the `config` subfolder
+inside your example folder. The folder will be then copied over to a temporary
+location before invoking the first file and then fed to CLI by passing the
+corresponding `--config` parameter. This way, you can prepare and execute
+CLI in an already prepared environment 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,
+replace `.in` and `.out` extension with `.in.static` and `.out.static`
+respectively. 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

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

@@ -0,0 +1,23 @@
+You are about to sign the following transaction:
+Method: staking.AmendCommissionSchedule
+Body:
+  Amendment:
+    Rates:
+      (1) start: epoch 29000
+          rate:  1.5%
+    Rate Bounds:
+      (1) start:        epoch 29000
+          minimum rate: 1.0%
+          maximum rate: 2.0%
+      (2) start:        epoch 35000
+          minimum rate: 0.9%
+          maximum rate: 1.9%
+Nonce:  1
+Fee:
+  Amount: 0.0 TEST
+  Gas limit: 1355
+  (gas price: 0.0 TEST per gas unit)
+
+Network:  testnet
+ParaTime: none (consensus layer)
+Account:  oscar

examples/account/burn.y.in

@@ -0,0 +1 @@
+oasis account burn 2.5

examples/account/burn.y.out

@@ -0,0 +1,13 @@
+You are about to sign the following transaction:
+Method: staking.Burn
+Body:
+  Amount: 2.5 TEST
+Nonce:  1
+Fee:
+  Amount: 0.0 TEST
+  Gas limit: 1235
+  (gas price: 0.0 TEST per gas unit)
+
+Network:  testnet
+ParaTime: none (consensus layer)
+Account:  oscar

examples/account/config/cli.toml

@@ -0,0 +1,132 @@
+[networks]
+default = 'testnet'
+
+[networks.mainnet]
+chain_context = 'b11b369e0da5bb230b220127f5e7b242d385ef8c6f54906243f30af63c815535'
+description = ''
+rpc = 'grpc.oasis.dev:443'
+
+[networks.mainnet.denomination]
+decimals = 9
+symbol = 'ROSE'
+
+[networks.mainnet.paratimes]
+default = 'emerald'
+
+[networks.mainnet.paratimes.cipher]
+description = ''
+id = '000000000000000000000000000000000000000000000000e199119c992377cb'
+
+[networks.mainnet.paratimes.cipher.denominations]
+[networks.mainnet.paratimes.cipher.denominations._]
+decimals = 9
+symbol = 'ROSE'
+
+[networks.mainnet.paratimes.emerald]
+description = ''
+id = '000000000000000000000000000000000000000000000000e2eaa99fc008f87f'
+
+[networks.mainnet.paratimes.emerald.denominations]
+[networks.mainnet.paratimes.emerald.denominations._]
+decimals = 18
+symbol = 'ROSE'
+
+[networks.mainnet.paratimes.sapphire]
+description = ''
+id = '000000000000000000000000000000000000000000000000f80306c9858e7279'
+
+[networks.mainnet.paratimes.sapphire.denominations]
+[networks.mainnet.paratimes.sapphire.denominations._]
+decimals = 18
+symbol = 'ROSE'
+
+[networks.testnet]
+chain_context = '50304f98ddb656620ea817cc1446c401752a05a249b36c9b90dba4616829977a'
+description = ''
+rpc = 'testnet.grpc.oasis.dev:443'
+
+[networks.testnet.denomination]
+decimals = 9
+symbol = 'TEST'
+
+[networks.testnet.paratimes]
+default = 'sapphire'
+
+[networks.testnet.paratimes.cipher]
+description = ''
+id = '0000000000000000000000000000000000000000000000000000000000000000'
+
+[networks.testnet.paratimes.cipher.denominations]
+[networks.testnet.paratimes.cipher.denominations._]
+decimals = 9
+symbol = 'TEST'
+
+[networks.testnet.paratimes.emerald]
+description = ''
+id = '00000000000000000000000000000000000000000000000072c8215e60d5bca7'
+
+[networks.testnet.paratimes.emerald.denominations]
+[networks.testnet.paratimes.emerald.denominations._]
+decimals = 18
+symbol = 'TEST'
+
+[networks.testnet.paratimes.sapphire]
+description = ''
+id = '000000000000000000000000000000000000000000000000a6d1e3ebf60dff6c'
+
+[networks.testnet.paratimes.sapphire.denominations]
+[networks.testnet.paratimes.sapphire.denominations._]
+decimals = 18
+symbol = 'TEST'
+
+[wallets]
+default = 'oscar'
+
+[wallets.emma]
+address = 'oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh'
+algorithm = 'secp256k1-raw'
+description = ''
+kind = 'file'
+number = 0
+
+[wallets.eric]
+address = 'oasis1qzplmfaeywvtc2qnylyhk0uzcxr4y5s3euhaug7q'
+algorithm = 'secp256k1-bip44'
+description = ''
+kind = 'file'
+number = 0
+
+[wallets.eugene]
+address = 'oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz'
+algorithm = 'secp256k1-bip44'
+description = ''
+kind = 'file'
+number = 0
+
+[wallets.lenny]
+address = 'oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall'
+algorithm = 'secp256k1-bip44'
+description = ''
+kind = 'ledger'
+number = 3
+
+[wallets.logan]
+address = 'oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl'
+algorithm = 'ed25519-legacy'
+description = ''
+kind = 'ledger'
+number = 0
+
+[wallets.orlando]
+address = 'oasis1qq84sc4q0shp5c5klwklqu59evz2mg59hveg7dqx'
+algorithm = 'ed25519-adr8'
+description = ''
+kind = 'file'
+number = 0
+
+[wallets.oscar]
+address = 'oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e'
+algorithm = 'ed25519-adr8'
+description = ''
+kind = 'file'
+number = 0

examples/account/config/emma.wallet

@@ -0,0 +1 @@
+{"kdf":{"argon2":{"salt":"+70IILRvyz2ISvRtFLp07WV5dJVZ3hTXPYLMjP7IR9Q=","time":1,"memory":65536,"threads":4}},"nonce":"OAVpbA7l6CxNuXmVe3981cq9Az2rRcUVd93KkHwpnoo=","data":"5Ij6aKiJPVxHWU2KyRQE055eErOysvECJw+6BYd4sJw2OubA+CuiIrhENzd9e3MC1cXdqlcUUS30p+5ASJrbgQ1IFe6WFcMncCUF8GEek9k+L5GMUCwrUStDb/rqlzILZifysmrffByQISas6IFXgy1I5WGC3xQ="}

examples/account/config/eric.wallet

@@ -0,0 +1 @@
+{"kdf":{"argon2":{"salt":"8BlOeFWkkcHOGxluM/pdOD4tCdhN+XkoNvSKNjc2G9k=","time":1,"memory":65536,"threads":4}},"nonce":"ZWAEpH7CzWECwuqnj58bfVipnjwzOm1JiYvlPJtuWTA=","data":"uDJ8SR0jAmc7HPhWF52czGFyjIgoYbEGKKfwhWReD5jJUvBoUR7Va2u1HaW0M9GJnPHAAMF3llRagAHaGzdz2zvyC+cewzH2Y4YhsI7ZZtq930sjPoxIMrbtm+8EdrPhF5AuES7tB6QoSjUhnwGo6lxfJd8CbSCFKRCfijqTMVV17K+t4WlGpTlZYUbuaeUjIniAUa0jydSzy3Ur2HwUEzZXRUWkM8QdCl+44Qhh3I3E2Kkcfc1X3rh4/3bzBKZSsrdH9j3nmH0OUt3X9Co53Tin5SGaf4z+"}

examples/account/config/eugene.wallet

@@ -0,0 +1 @@
+{"kdf":{"argon2":{"salt":"VPbTQJminqFbuM10OjLb1Rs5zYDbZV/QP1SlZHlHh1M=","time":1,"memory":65536,"threads":4}},"nonce":"XbvEzIhTIyh+HhVntQen1DEEwJJHQsyRGGczL0h55dE=","data":"LHzfNmIwD4AS9F5lp6io/KcEhDoBHrkJPOhOZ1C/a+YZlsqhFnXW5esSNDi48Oe6iMqVrtxApyxRb8rI+ZFI+lMREzalfXpO5GV42ny7h2bwvGON5ItE1DhkqTtbYKU3Fy/Z07sr2SzGBxtdsL4OPtKVSMvV4mm69aBLbLf4lUN3cAX6mbTrrEgAswBISW6EDDwYG6LkdIUSjok="}

examples/account/config/orlando.wallet

@@ -0,0 +1 @@
+{"kdf":{"argon2":{"salt":"aMWiNKkObdbJ5YBrAjAAV3DonFMwdCpIoWp8RXyagpM=","time":1,"memory":65536,"threads":4}},"nonce":"KUlVqgbRw9roZj6KiJk47uXJ4ohzZNiznouXDwJ2yDE=","data":"muSrgs8iJrRusaAPaWu0d/4TysA9RM2BH+Ddw8c4gav5FxU3R/z7V7kOk7ZjXN6F8S9T1cenmmn4uESVgIs333YRGOBCVwxV2+dxrVlr7GAzi2uicWAU5tsUbBbdgxepKVoWWRKBeRfbJXZVTu8WM+4ZQPGhry9DdR98mvdueNtLqChMGxYoKOGiApj36u6i+xRJrOa4cKsLyNMPqQn4BI5GL4FbhSbIB3vhHQZ3pA1gvagIc1/MGy/hvmcsteDbBn7m/vjG"}

examples/account/config/oscar.wallet

@@ -0,0 +1 @@
+{"kdf":{"argon2":{"salt":"PMXSZ2OIM2q7YyLHKUrAotJBANA7QLOaEWDzpYcQ81g=","time":1,"memory":65536,"threads":4}},"nonce":"rWq6PYJWjGqGGueSafq2O1Zz1Gshx4gjpweryfCGFFo=","data":"nIzNG8TASLoZqINSVcQhW/9IFuMJ9+U+Hm9tB3m3Fnnua74jekDRVHIFzKmi7Z2tkV/KfIJyKsqdfPMM0O5aJbXW/qSZl7Wma4JNh3MgOrH4m9wvEWF/vzGgs4EctZnlao3y2DxQtedivPjyg6k1qWSP3RQoyLY/fliTaNETDpqbc08xOuhmVKzSse2UxZazpChVU55LA9wiwKN5Mfw+i3bEueiHuet8ECnax/rbGPTEnHMjmtGC9D69VWLBXn+NNIW2WQYuPvDkHBQS/zqT"}

examples/account/delegate.y.in

@@ -0,0 +1 @@
+oasis account delegate 20 oasis1qpkl3vykn9mf4xcq9eevmey4ffrzf0ajtcpvd7sk --no-paratime

examples/account/delegate.y.out

@@ -0,0 +1,14 @@
+You are about to sign the following transaction:
+Method: staking.AddEscrow
+Body:
+  To:     oasis1qpkl3vykn9mf4xcq9eevmey4ffrzf0ajtcpvd7sk
+  Amount: 20.0 TEST
+Nonce:  1
+Fee:
+  Amount: 0.0 TEST
+  Gas limit: 1271
+  (gas price: 0.0 TEST per gas unit)
+
+Network:  testnet
+ParaTime: none (consensus layer)
+Account:  oscar

examples/account/deposit-eth.y.in

@@ -0,0 +1 @@
+oasis accounts deposit 10 0x90adE3B7065fa715c7a150313877dF1d33e777D5 --gas-price 0