|
| 1 | +# Oasis CLI Examples |
| 2 | + |
| 3 | +This folder contains example scenarios for the Oasis CLI. The snippets are |
| 4 | +included in the documentation and also serve as a check for potential |
| 5 | +regressions in the CLI. |
| 6 | + |
| 7 | +Each example is stored inside its own folder. The folder contains: |
| 8 | + |
| 9 | +- one or more invocation files, |
| 10 | +- output file for each invocation file with the content of the resulting |
| 11 | + standard output, |
| 12 | +- input and output artifacts |
| 13 | +- `config` folder containing custom config file to be used for the scenario. |
| 14 | + |
| 15 | +## Invocation files |
| 16 | + |
| 17 | +Invocation files have `.in` extension and they will be executed in |
| 18 | +alphabetic order. This is important, if you have destructive operations (e.g |
| 19 | +adding or removing a wallet) where the order of execution should be respected. |
| 20 | +In this case, name the files starting with a number, for example `00-create.in`. |
| 21 | + |
| 22 | +Each `.in` file begins with `oasis` command, which will be replaced with the |
| 23 | +path to the actual Oasis CLI command when generating example outputs. |
| 24 | + |
| 25 | +An example invocation file content to create a new wallet: |
| 26 | + |
| 27 | +``` |
| 28 | +oasis wallet create john |
| 29 | +``` |
| 30 | + |
| 31 | +### Non-Interactive Execution |
| 32 | + |
| 33 | +If you want to invoke Oasis in a non-interactive mode (by appending |
| 34 | +`-y -o /dev/null` parameters), replace the `.in` extension with `.y.in`. For |
| 35 | +example `00-create.in` becomes `00-create.y.in`. |
| 36 | + |
| 37 | +### Custom Config Files |
| 38 | + |
| 39 | +Sometimes, you want to use a predefined config file for the Oasis CLI. Put |
| 40 | +your desired `cli.toml` and the wallet files to the `config` subfolder |
| 41 | +inside your example folder. The folder will be then copied over to a temporary |
| 42 | +location before invoking the first file and then fed to CLI by passing the |
| 43 | +corresponding `--config` parameter. This way, you can prepare and execute |
| 44 | +CLI in an already prepared environment without a dozen of presteps. |
| 45 | + |
| 46 | +### Example Artifacts |
| 47 | + |
| 48 | +If an example requires external files such as a JSON file containing an entity |
| 49 | +descriptor or a raw transaction, simply put it alongside the input file. |
| 50 | +Assume the working directory will be the one that the input file resides in. |
| 51 | +The same goes for the output artifacts (e.g. signed transaction). |
| 52 | + |
| 53 | +## Output Files |
| 54 | + |
| 55 | +The Oasis CLI output for the given input will be stored in a file named the same |
| 56 | +as the corresponding invocation file, but having `.out` extension instead of |
| 57 | +`.in`. |
| 58 | + |
| 59 | +Scenarios should be designed in a way that the output files remain equal unless |
| 60 | +a different behavior of the Oasis CLI is expected. |
| 61 | + |
| 62 | +## Static examples |
| 63 | + |
| 64 | +If you do not want the example to be executed, but you simply want to store |
| 65 | +Oasis CLI execution snippets for example to be included in the documentation, |
| 66 | +replace `.in` and `.out` extension with `.in.static` and `.out.static` |
| 67 | +respectively. Such files will not be tested and regenerated each time, but you |
| 68 | +will have to update it manually. We discourage using this mechanism, but it may |
| 69 | +be useful in cases when the output is expected to change and would not make |
| 70 | +sense to update it each time (e.g. `oasis network status` returns the current |
| 71 | +block height). |
| 72 | + |
| 73 | +## Running Examples |
| 74 | + |
| 75 | +To run the examples and generate outputs, invoke in the top-level directory: |
| 76 | + |
| 77 | +```sh |
| 78 | +make examples |
| 79 | +``` |
0 commit comments