diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contributing.rst | 79 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 20 | ||||
| -rw-r--r-- | docs/units-and-global-variables.rst | 4 |
3 files changed, 100 insertions, 3 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 8b4695e4..1bcaed7c 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -91,6 +91,85 @@ Alternatively, there is a testing script at ``scripts/test.sh`` which executes a Travis CI even runs some additional tests (including ``solc-js`` and testing third party Solidity frameworks) that require compiling the Emscripten target. +Writing and running syntax tests +-------------------------------- + +As mentioned above, syntax tests are stored in individual contracts. These files must contain annotations, stating the expected result(s) of the respective test. +The test suite will compile and check them against the given expectations. + +Example: ``./test/libsolidity/syntaxTests/double_stateVariable_declaration.sol`` + +:: + + contract test { + uint256 variable; + uint128 variable; + } + // ---- + // DeclarationError: Identifier already declared. + +A syntax test must contain at least the contract under test itself, followed by the seperator ``----``. The additional comments above are used to describe the +expected compiler errors or warnings. This section can be empty in case that the contract should compile without any errors or warnings. + +In the above example, the state variable ``variable`` was declared twice, which is not allowed. This will result in a ``DeclarationError`` stating that the identifer was already declared. + +The tool that is being used for those tests is called ``isoltest`` and can be found under ``./test/tools/``. It is an interactive tool which allows +editing of failing contracts using your prefered text editor. Let's try to break this test by removing the second declaration of ``variable``: + +:: + + contract test { + uint256 variable; + } + // ---- + // DeclarationError: Identifier already declared. + +Running ``./test/isoltest`` again will result in a test failure: + +:: + + syntaxTests/double_stateVariable_declaration.sol: FAIL + Contract: + contract test { + uint256 variable; + } + + Expected result: + DeclarationError: Identifier already declared. + Obtained result: + Success + + +which prints the expected result next to the obtained result, but also provides a way to change edit / update / skip the current contract or to even quit. +``isoltest`` offers several options for failing tests: + +- edit: ``isoltest`` will try to open the editor that was specified before using ``isoltest --editor /path/to/editor``. If no path was set, this will result in a runtime error. In case an editor was specified, this will open it such that the contract can be adjusted. +- update: Updates the contract under test. This will either remove the annotation which contains the exception not met or will add missing expectations. The test will then be run again. +- skip: Skips the execution of this particular test. +- quit: Quits ``isoltest``. + +Automatically updating the test above will change it to + +:: + + contract test { + uint256 variable; + } + // ---- + +and re-run the test. It will now pass again: + +:: + + Re-running test case... + syntaxTests/double_stateVariable_declaration.sol: OK + + +.. note:: + + Please choose a name for the contract file, that is self-explainatory in the sense of what is been tested, e.g. ``double_variable_declaration.sol``. + Do not put more than one contract into a single file. ``isoltest`` is currently not able to recognize them individually. + Whiskers ======== diff --git a/docs/miscellaneous.rst b/docs/miscellaneous.rst index a7d5c445..01154854 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -314,7 +314,7 @@ The following is the order of precedence for operators, listed in order of evalu Global Variables ================ -- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks +- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent, excluding current, blocks - deprecated in version 0.4.22 and replaced by ``blockhash(uint blockNumber)``. - ``block.coinbase`` (``address``): current block miner's address - ``block.difficulty`` (``uint``): current block difficulty - ``block.gaslimit`` (``uint``): current block gaslimit @@ -331,6 +331,7 @@ Global Variables - ``assert(bool condition)``: abort execution and revert state changes if condition is ``false`` (use for internal error) - ``require(bool condition)``: abort execution and revert state changes if condition is ``false`` (use for malformed input or error in external component) - ``revert()``: abort execution and revert state changes +- ``blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks - ``keccak256(...) returns (bytes32)``: compute the Ethereum-SHA-3 (Keccak-256) hash of the :ref:`(tightly packed) arguments <abi_packed_mode>` - ``sha3(...) returns (bytes32)``: an alias to ``keccak256`` - ``sha256(...) returns (bytes32)``: compute the SHA-256 hash of the :ref:`(tightly packed) arguments <abi_packed_mode>` @@ -346,6 +347,23 @@ Global Variables - ``<address>.send(uint256 amount) returns (bool)``: send given amount of Wei to :ref:`address`, returns ``false`` on failure - ``<address>.transfer(uint256 amount)``: send given amount of Wei to :ref:`address`, throws on failure +.. note:: + Do not rely on ``block.timestamp``, ``now`` and ``blockhash`` as a source of randomness, + unless you know what you are doing. + + Both the timestamp and the block hash can be influenced by miners to some degree. + Bad actors in the mining community can for example run a casino payout function on a chosen hash + and just retry a different hash if they did not receive any money. + + The current block timestamp must be strictly larger than the timestamp of the last block, + but the only guarantee is that it will be somewhere between the timestamps of two + consecutive blocks in the canonical chain. + +.. note:: + The block hashes are not available for all blocks for scalability reasons. + You can only access the hashes of the most recent 256 blocks, all other + values will be zero. + .. index:: visibility, public, private, external, internal Function Visibility Specifiers diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst index d789e87f..2571f20a 100644 --- a/docs/units-and-global-variables.rst +++ b/docs/units-and-global-variables.rst @@ -52,7 +52,7 @@ namespace and are mainly used to provide information about the blockchain. Block and Transaction Properties -------------------------------- -- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks excluding current +- ``block.blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent, excluding current, blocks - deprecated in version 0.4.22 and replaced by ``blockhash(uint blockNumber)``. - ``block.coinbase`` (``address``): current block miner's address - ``block.difficulty`` (``uint``): current block difficulty - ``block.gaslimit`` (``uint``): current block gaslimit @@ -74,7 +74,7 @@ Block and Transaction Properties This includes calls to library functions. .. note:: - Do not rely on ``block.timestamp``, ``now`` and ``block.blockhash`` as a source of randomness, + Do not rely on ``block.timestamp``, ``now`` and ``blockhash`` as a source of randomness, unless you know what you are doing. Both the timestamp and the block hash can be influenced by miners to some degree. |