aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorErik Kundt <bitshift@posteo.org>2018-03-21 19:47:08 +0800
committerErik Kundt <bitshift@posteo.org>2018-03-22 02:35:22 +0800
commit9d9c0bf908c4b61f72595ffca530d7d3fc4d28c2 (patch)
tree67a89e48a0dcc788f0c50c44ae20fae3204e781a
parent2b2527f31ce3e7946b35759a1ac4a096c918b91c (diff)
downloaddexon-solidity-9d9c0bf908c4b61f72595ffca530d7d3fc4d28c2.tar.gz
dexon-solidity-9d9c0bf908c4b61f72595ffca530d7d3fc4d28c2.tar.zst
dexon-solidity-9d9c0bf908c4b61f72595ffca530d7d3fc4d28c2.zip
Updates "How to contribute"
Adds detailed description of the new syntax test tool.
-rw-r--r--docs/contributing.rst62
1 files changed, 62 insertions, 0 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 8b4695e4..08c125f9 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -91,6 +91,68 @@ 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.
+
+
+The comments in the contract above are used to describe the expected compiler errors. 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 remove the annotation which contains the exception not met and runs this test again.
+- skip: Skips the execution of this particular test.
+- quit: Quits ``isoltest``.
+
+
+.. 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
========