From 016107d8c35fc3a2a70e035a270a91e494499b8d Mon Sep 17 00:00:00 2001 From: hanabi1224 Date: Wed, 15 Jan 2025 21:38:42 +0800 Subject: [PATCH 1/3] docs: RPC test snapshot --- .../developers/guides/rpc_test_snapshot.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/docs/developers/guides/rpc_test_snapshot.md diff --git a/docs/docs/developers/guides/rpc_test_snapshot.md b/docs/docs/developers/guides/rpc_test_snapshot.md new file mode 100644 index 00000000000..034f75a2183 --- /dev/null +++ b/docs/docs/developers/guides/rpc_test_snapshot.md @@ -0,0 +1,32 @@ +--- +title: RPC Test Snapshots +sidebar_position: 2 +--- + +This document describes how RPC test snapshots can be generated and used. An RPC test snapshot contains the name of the RPC method, the request payload, the desired response and the minimal database entries for replaying the request. Thus it can be used as a regression test or a unit test for an RPC method. + +### Generate RPC test dumps + +An RPC test dump contains the name of the RPC method, the request payload and the response of an RPC call. It is used for further dumping a minimal database snapshot for replaying the request in a subsequent process. + +To generate test dumps, simply adding `--dump-dir [PATH]` to `forest-tool api compare` command. e.g. `forest-tool api compare forest_snapshot_calibnet_2025-01-15_height_2320334.forest.car.zst --dump-dir /var/tmp/rpc-dump` + +### Generate RPC test snapshots + +As described above, an RPC test snapshot is generated from an RPC test dump and includes the extra minimal database snapshot in Forest CAR format. + +The `forest-tool api generate-test-snapshot` command is for this purpose, note that it takes the database path of the Forest daemon against which the `forest-tool api compare` command in the previous step is run, to dump the minimal database snapshot. e.g. `forest-tool api generate-test-snapshot --db ~/.local/share/forest/calibnet/0.23.3 --chain calibnet --out-dir /var/tmp/rpc-snapshots /var/tmp/test-dumps/filecoin_stategetallallocations*.json` + +### (Optional) compress the test snapshots + +A test snapshot that is generated in the previous step is in JSON format, for easier inspection of the content. The Forest tool set supports `.zst` archives of test snapshots for better disk usage and network bandwidth efficiency. Simply run `zstd /var/tmp/rpc-snapshots/*.json` + +### Verify the test snapshots + +`forest-tool api test /var/tmp/rpc-snapshots/*.json` or `forest-tool api test /var/tmp/rpc-snapshots/*.zst`. As mentioned above, both `json` and `.json.zst` formats are supported. + +### Run test snapshots in unit tests + +- upload the test snapshots (.zst archive is recommended) to the Digital Ocean space `forest-snapshots/rpc_test` +- include the file names in `src/tool/subcommands/api_cmd/test_snapshots.txt` +- run `cargo test --lib -- --test rpc_regression_tests --nocapture` From 8585b67d5553ea4f7a33454bc14321e9239e39a5 Mon Sep 17 00:00:00 2001 From: hanabi1224 Date: Thu, 16 Jan 2025 17:30:01 +0800 Subject: [PATCH 2/3] run through grammarly --- docs/docs/developers/guides/rpc_test_snapshot.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/docs/developers/guides/rpc_test_snapshot.md b/docs/docs/developers/guides/rpc_test_snapshot.md index 034f75a2183..02f3e59b8a0 100644 --- a/docs/docs/developers/guides/rpc_test_snapshot.md +++ b/docs/docs/developers/guides/rpc_test_snapshot.md @@ -3,13 +3,13 @@ title: RPC Test Snapshots sidebar_position: 2 --- -This document describes how RPC test snapshots can be generated and used. An RPC test snapshot contains the name of the RPC method, the request payload, the desired response and the minimal database entries for replaying the request. Thus it can be used as a regression test or a unit test for an RPC method. +This document describes how to generate and use RPC test snapshots. An RPC test snapshot contains the name of the RPC method, the request payload, the desired response, and the minimal database entries for replaying the request. Thus, it can be used as a regression test or a unit test for an RPC method. ### Generate RPC test dumps -An RPC test dump contains the name of the RPC method, the request payload and the response of an RPC call. It is used for further dumping a minimal database snapshot for replaying the request in a subsequent process. +An RPC test dump contains the name of the RPC method, the request payload, and the response of an RPC call. It is used to dump a minimal database snapshot and replay the request in a subsequent process. -To generate test dumps, simply adding `--dump-dir [PATH]` to `forest-tool api compare` command. e.g. `forest-tool api compare forest_snapshot_calibnet_2025-01-15_height_2320334.forest.car.zst --dump-dir /var/tmp/rpc-dump` +To generate test dumps, add `--dump-dir [PATH]` to `forest-tool api compare` command. e.g., `forest-tool api compare forest_snapshot_calibnet_2025-01-15_height_2320334.forest.car.zst --dump-dir /var/tmp/rpc-dump` ### Generate RPC test snapshots @@ -19,14 +19,14 @@ The `forest-tool api generate-test-snapshot` command is for this purpose, note t ### (Optional) compress the test snapshots -A test snapshot that is generated in the previous step is in JSON format, for easier inspection of the content. The Forest tool set supports `.zst` archives of test snapshots for better disk usage and network bandwidth efficiency. Simply run `zstd /var/tmp/rpc-snapshots/*.json` +A test snapshot generated in the previous step is in JSON format, for easier inspection of the content. The Forest tool set supports `.zst` archives of test snapshots for better disk usage and network bandwidth efficiency. Just run `zstd /var/tmp/rpc-snapshots/*.json` ### Verify the test snapshots -`forest-tool api test /var/tmp/rpc-snapshots/*.json` or `forest-tool api test /var/tmp/rpc-snapshots/*.zst`. As mentioned above, both `json` and `.json.zst` formats are supported. +`forest-tool api test /var/tmp/rpc-snapshots/*.json` or `forest-tool api test /var/tmp/rpc-snapshots/*.zst`. As mentioned above, both `.json` and `.json.zst` formats are supported. -### Run test snapshots in unit tests +### Run the test snapshots in unit tests -- upload the test snapshots (.zst archive is recommended) to the Digital Ocean space `forest-snapshots/rpc_test` +- upload the test snapshots (`.zst` format is recommended) to the Digital Ocean space `forest-snapshots/rpc_test` - include the file names in `src/tool/subcommands/api_cmd/test_snapshots.txt` - run `cargo test --lib -- --test rpc_regression_tests --nocapture` From 2cb8e9b075ac622d8b33495ceec728a13d5829d1 Mon Sep 17 00:00:00 2001 From: hanabi1224 Date: Fri, 17 Jan 2025 07:31:54 +0800 Subject: [PATCH 3/3] resolve comments --- docs/docs/developers/guides/rpc_test_snapshot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/developers/guides/rpc_test_snapshot.md b/docs/docs/developers/guides/rpc_test_snapshot.md index 02f3e59b8a0..befeb74f097 100644 --- a/docs/docs/developers/guides/rpc_test_snapshot.md +++ b/docs/docs/developers/guides/rpc_test_snapshot.md @@ -9,7 +9,7 @@ This document describes how to generate and use RPC test snapshots. An RPC test An RPC test dump contains the name of the RPC method, the request payload, and the response of an RPC call. It is used to dump a minimal database snapshot and replay the request in a subsequent process. -To generate test dumps, add `--dump-dir [PATH]` to `forest-tool api compare` command. e.g., `forest-tool api compare forest_snapshot_calibnet_2025-01-15_height_2320334.forest.car.zst --dump-dir /var/tmp/rpc-dump` +To generate test dumps, add `--dump-dir [PATH]` to `forest-tool api compare` command. e.g., `forest-tool api compare forest_snapshot_calibnet_2025-01-15_height_2320334.forest.car.zst --dump-dir /var/tmp/rpc-dump`. Note that a running instance of each Forest and Lotus is required. (Refer to `scripts/tests/api_compare/docker-compose.yml` to setup Lotus with extra environment variables) ### Generate RPC test snapshots