github.com/Finschia/finschia-sdk@v0.48.1/x/simulation/doc.go (about)

     1  /*
     2  Package simulation implements a full fledged Cosmos SDK application used for executing
     3  simulation test suites.
     4  
     5  # Simulation App
     6  
     7  The SimApp type defines an application used for running extensive simulation
     8  testing suites. It contains all core modules, including governance, staking,
     9  slashing, and distribution.
    10  
    11  Simulation is executed with various inputs including the number of blocks to
    12  simulate, the block size, whether the app should commit or not, the invariant
    13  checking period, and a seed which is used as a source of pseudo-randomness.
    14  
    15  In addition to the various inputs, simulation runs mainly in three modes:
    16  
    17  1. Completely random where the initial state, module parameters and simulation
    18  parameters are pseudo-randomly generated.
    19  
    20  2. From a genesis file where the initial state and the module parameters are defined.
    21  This mode is helpful for running simulations on a known state such as a live
    22  network export where a new (mostly likely breaking) version of the application
    23  needs to be tested.
    24  
    25  3. From a params file where the initial state is pseudo-randomly generated but the
    26  module and simulation parameters can be provided manually. This allows for a more
    27  controlled and deterministic simulation setup while allowing the state space to
    28  still be pseudo-randomly simulated.
    29  
    30  The simulation test suite also supports testing determinism and import/export
    31  functionality.
    32  
    33  # Randomness
    34  
    35  Currently, simulation uses a single seed (integer) as a source for a PRNG by
    36  which all random operations are executed from. Any call to the PRNG changes all
    37  future operations as the internal state of the PRNG is modified. For example,
    38  if a new message type is created and needs to be simulated, the new introduced
    39  PRNG call will change all subsequent operations.
    40  
    41  This may can often be problematic when testing fixes to simulation faults. One
    42  current solution to this is to use a params file as mentioned above. In the future
    43  the simulation suite is expected to support a series of PRNGs that can be used
    44  uniquely per module and simulation component so that they will not effect each
    45  others state execution outcome.
    46  
    47  # Usage
    48  
    49  To execute a completely pseudo-random simulation:
    50  
    51  	 $ go test -mod=readonly github.com/Finschia/finschia-sdk/simapp \
    52  		-run=TestFullAppSimulation \
    53  		-Enabled=true \
    54  		-NumBlocks=100 \
    55  		-BlockSize=200 \
    56  		-Commit=true \
    57  		-Seed=99 \
    58  		-Period=5 \
    59  		-v -timeout 24h
    60  
    61  To execute simulation from a genesis file:
    62  
    63  	 $ go test -mod=readonly github.com/Finschia/finschia-sdk/simapp \
    64  	 	-run=TestFullAppSimulation \
    65  	 	-Enabled=true \
    66  	 	-NumBlocks=100 \
    67  	 	-BlockSize=200 \
    68  	 	-Commit=true \
    69  	 	-Seed=99 \
    70  	 	-Period=5 \
    71  		-Genesis=/path/to/genesis.json \
    72  	 	-v -timeout 24h
    73  
    74  To execute simulation from a simulation params file:
    75  
    76  	 $ go test -mod=readonly github.com/Finschia/finschia-sdk/simapp \
    77  		-run=TestFullAppSimulation \
    78  		-Enabled=true \
    79  		-NumBlocks=100 \
    80  		-BlockSize=200 \
    81  		-Commit=true \
    82  		-Seed=99 \
    83  		-Period=5 \
    84  		-Params=/path/to/params.json \
    85  		-v -timeout 24h
    86  
    87  To export the simulation params to a file at a given block height:
    88  
    89  	 $ go test -mod=readonly github.com/Finschia/finschia-sdk/simapp \
    90  	 	-run=TestFullAppSimulation \
    91  	 	-Enabled=true \
    92  	 	-NumBlocks=100 \
    93  	 	-BlockSize=200 \
    94  	 	-Commit=true \
    95  	 	-Seed=99 \
    96  	 	-Period=5 \
    97  		-ExportParamsPath=/path/to/params.json \
    98  		-ExportParamsHeight=50 \
    99  		 -v -timeout 24h
   100  
   101  To export the simulation app state (i.e genesis) to a file:
   102  
   103  	 $ go test -mod=readonly github.com/Finschia/finschia-sdk/simapp \
   104  	 	-run=TestFullAppSimulation \
   105  	 	-Enabled=true \
   106  	 	-NumBlocks=100 \
   107  	 	-BlockSize=200 \
   108  	 	-Commit=true \
   109  	 	-Seed=99 \
   110  	 	-Period=5 \
   111  		-ExportStatePath=/path/to/genesis.json \
   112  		 v -timeout 24h
   113  
   114  # Params
   115  
   116  Params that are provided to simulation from a JSON file are used to used to set
   117  both module parameters and simulation parameters. See sim_test.go for the full
   118  set of parameters that can be provided.
   119  */
   120  package simulation