address pr comments, add doc comments

crates/sui-graphql-rpc/src/test_infra/cluster.rs

@@ -174,12 +174,16 @@ pub async fn serve_executor(
         .parse()
         .unwrap();
 
+    info!("Starting executor server on {}", executor_server_url);
+
     let executor_server_handle = tokio::spawn(async move {
         sui_rest_api::RestService::new_without_version(executor)
             .start_service(executor_server_url)
             .await;
     });
 
+    info!("spawned executor server");
+
     let snapshot_config = snapshot_config.unwrap_or_default();
 
     let (pg_store, pg_handle, _) = start_indexer_writer_for_testing(

crates/sui-transactional-test-runner/src/args.rs

@@ -75,11 +75,12 @@ pub struct SuiInitArgs {
     /// the indexer.
     #[clap(long = "epochs-to-keep")]
     pub epochs_to_keep: Option<u64>,
-    /// TODO (wlmyng): doc comment
-    #[clap(long = "data-ingestion-path")]
+    /// Dir for simulacrum to write checkpoint files to. To be passed to the offchain indexer and
+    /// reader.
+    #[clap(long)]
     pub data_ingestion_path: Option<PathBuf>,
-    /// TODO (wlmyng): doc comment
-    #[clap(long = "rest-api-url")]
+    /// URL for the Sui REST API. To be passed to the offchain indexer and reader.
+    #[clap(long)]
     pub rest_api_url: Option<String>,
 }
 

crates/sui-transactional-test-runner/src/offchain_state.rs

@@ -10,11 +10,18 @@ pub struct TestResponse {
     pub service_version: Option<String>,
 }
 
+/// Trait for interacting with the offchain state of the Sui network. To reduce test flakiness,
+/// these methods are used in the `RunGraphqlCommand` to stabilize the off-chain indexed state.
 #[async_trait]
 pub trait OffchainStateReader: Send + Sync + 'static {
+    /// Polls the objects snapshot table until it is within the allowed lag from the latest
+    /// checkpoint.
     async fn wait_for_objects_snapshot_catchup(&self, base_timeout: Duration);
+    /// Polls the checkpoint table until the given checkpoint is committed.
     async fn wait_for_checkpoint_catchup(&self, checkpoint: u64, base_timeout: Duration);
+    /// Polls the checkpoint table until the given checkpoint is pruned.
     async fn wait_for_pruned_checkpoint(&self, checkpoint: u64, base_timeout: Duration);
+    /// Executes a GraphQL query and returns the response.
     async fn execute_graphql(
         &self,
         query: String,

crates/sui-transactional-test-runner/src/test_adapter.rs

@@ -127,11 +127,14 @@ const DEFAULT_CHAIN_START_TIMESTAMP: u64 = 0;
 
 /// Extra args related to configuring the indexer and reader.
 // TODO: the configs are still tied to the indexer crate, eventually we'd like a new command that is
-// more agnostic.
+// more agnostic
 pub struct OffChainConfig {
     pub snapshot_config: SnapshotLagConfig,
     pub retention_config: Option<RetentionConfig>,
+    /// Dir for simulacrum to write checkpoint files to. To be passed to the offchain indexer if it
+    /// uses file-based ingestion.
     pub data_ingestion_path: PathBuf,
+    /// URL for the Sui REST API. To be passed to the offchain indexer if it uses the REST API.
     pub rest_api_url: Option<String>,
 }
 
@@ -148,6 +151,9 @@ pub struct SuiTestAdapter {
     pub(crate) staged_modules: BTreeMap<Symbol, StagedPackage>,
     is_simulator: bool,
     pub(crate) executor: Box<dyn TransactionalAdapter>,
+    /// If `is_simulator` is true, the executor will be a `Simulacrum`, and this will be a
+    /// `RestStateReader` that can be used to spawn the equivalent of a fullnode rest api. This can
+    /// then be used to serve an indexer that reads from said rest api service.
     pub read_replica: Option<Arc<dyn RestStateReader + Send + Sync>>,
     /// Configuration for offchain state reader read from the file itself, and can be passed to the
     /// specific indexing and reader flavor.
@@ -165,6 +171,8 @@ struct AdapterInitConfig {
     reference_gas_price: Option<u64>,
     default_gas_price: Option<u64>,
     flavor: Option<Flavor>,
+    /// Configuration for offchain state reader read from the file itself, and can be passed to the
+    /// specific indexing and reader flavor.
     offchain_config: Option<OffChainConfig>,
 }