Adds documentation and fixes to semantic test framework.

Author: erak

test/ExecutionFramework.h

@@ -53,7 +53,7 @@ class ExecutionFramework
 
 public:
 	ExecutionFramework();
-	ExecutionFramework(std::string const& _ipcPath);
+	explicit ExecutionFramework(std::string const& _ipcPath);
 	virtual ~ExecutionFramework() = default;
 
 	virtual bytes const& compileAndRunWithoutCheck(

test/libsolidity/SemanticTest.cpp

@@ -84,15 +84,15 @@ bool SemanticTest::run(ostream& _stream, string const& _linePrefix, bool const _
 		FormattedScope(_stream, _formatted, {BOLD, CYAN}) << _linePrefix << "Expected result:" << endl;
 		for (auto const& test: m_tests)
 		{
-			printFunctionCall(_stream, test.call, _linePrefix);
-			printFunctionCallTest(_stream, test, true, _linePrefix, _formatted);
+			printFunctionCallHighlighted(_stream, test.call, _linePrefix);
+			printFunctionCallTestHighlighted(_stream, test, true, _linePrefix, _formatted);
 		}
 
 		FormattedScope(_stream, _formatted, {BOLD, CYAN}) << _linePrefix << "Obtained result:" << endl;
 		for (auto const& test: m_tests)
 		{
-			printFunctionCall(_stream, test.call, _linePrefix);
-			printFunctionCallTest(_stream, test, false, _linePrefix, _formatted);
+			printFunctionCallHighlighted(_stream, test.call, _linePrefix);
+			printFunctionCallTestHighlighted(_stream, test, false, _linePrefix, _formatted);
 		}
 		return false;
 	}
@@ -111,8 +111,8 @@ void SemanticTest::printUpdatedExpectations(ostream& _stream, string const& _lin
 {
 	for (auto const& test: m_tests)
 	{
-		printFunctionCall(_stream, test.call, _linePrefix);
-		printFunctionCallTest(_stream, test, false, _linePrefix);
+		printFunctionCallHighlighted(_stream, test.call, _linePrefix);
+		printFunctionCallTestHighlighted(_stream, test, false, _linePrefix);
 	}
 }
 
@@ -121,16 +121,16 @@ void SemanticTest::parseExpectations(istream& _stream)
 {
 	TestFileParser parser{_stream};
 	for (auto const& call: parser.parseFunctionCalls())
-		m_tests.emplace_back(FunctionCallTest{std::move(call), false, bytes{}, string{}});
+		m_tests.emplace_back(FunctionCallTest{call, bytes{}, string{}});
 }
 
 bool SemanticTest::deploy(string const& _contractName, u256 const& _value, bytes const& _arguments)
 {
-	auto output = compileAndRunWithoutCheck(m_source, _value, _contractName, _arguments, m_libraryAddresses);
+	auto output = compileAndRunWithoutCheck(m_source, _value, _contractName, _arguments);
 	return !output.empty() && m_transactionSuccessful;
 }
 
-void SemanticTest::printFunctionCall(ostream& _stream, FunctionCall const& _call, string const& _linePrefix) const
+void SemanticTest::printFunctionCallHighlighted(ostream& _stream, FunctionCall const& _call, string const& _linePrefix) const
 {
 	_stream << _linePrefix << _call.signature;
 	if (_call.value > u256(0))
@@ -142,18 +142,18 @@ void SemanticTest::printFunctionCall(ostream& _stream, FunctionCall const& _call
 	_stream << endl;
 }
 
-void SemanticTest::printFunctionCallTest(
+void SemanticTest::printFunctionCallTestHighlighted(
 	ostream& _stream,
 	FunctionCallTest const& _test,
-	bool _expected,
+	bool _printExcepted,
 	string const& _linePrefix,
 	bool const _formatted
 ) const
 {
 	_stream << _linePrefix;
 	if (_formatted && !_test.matchesExpectation())
 		_stream << formatting::RED_BACKGROUND;
-	string output = _expected ? _test.call.expectations.output : _test.output;
+	string output = _printExcepted ? _test.call.expectations.output : _test.output;
 	_stream << boost::algorithm::trim_copy(output);
 	if (_formatted && !_test.matchesExpectation())
 		_stream << formatting::RESET;

test/libsolidity/SemanticTest.h

@@ -33,11 +33,17 @@ namespace solidity
 namespace test
 {
 
+/**
+ * Class that represents a semantic test (or end-to-end test) and allows running it as part of the
+ * boost unit test environment or isoltest. It reads the Solidity source and an additional comment
+ * section from the given file. This comment section should define a set of functions to be called
+ * and an expected result they return after being executed.
+ */
 class SemanticTest: public SolidityExecutionFramework, public TestCase
 {
 public:
 	static std::unique_ptr<TestCase> create(Config const& _options)
-	{ return std::unique_ptr<TestCase>(new SemanticTest(_options.filename, _options.ipcPath)); }
+	{ return std::make_unique<SemanticTest>(_options.filename, _options.ipcPath); }
 
 	explicit SemanticTest(std::string const& _filename, std::string const& _ipcPath);
 
@@ -46,17 +52,28 @@ class SemanticTest: public SolidityExecutionFramework, public TestCase
 	void printUpdatedExpectations(std::ostream& _stream, std::string const& _linePrefix = "") const override;
 
 private:
+	/**
+	 * Represents a function call and the result it returned. It stores the call
+	 * representation itself, the actual byte result (if any) and a string representation
+	 * used for the interactive update routine provided by isoltest. It also provides
+	 * functionality to compare the actual result with the expectations attached to the
+	 * call object, as well as a way to reset the result if executed multiple times.
+	 */
 	struct FunctionCallTest
 	{
 		FunctionCall call;
-		bool status;
 		bytes rawBytes;
 		std::string output;
+		bool status = false;
+		/// Compares raw expectations (which are converted to a byte representation before),
+		/// and also the expected transaction status of the function call to the actual test results.
 		bool matchesExpectation() const
 		{
 			auto expectedByteFormat = TestFileParser::formattedStringToBytes(call.expectations.raw);
 			return status == call.expectations.status && rawBytes == expectedByteFormat.first;
 		}
+		/// Resets current results in case the function was called and the result
+		/// stored already (e.g. if test case was updated via isoltest).
 		void reset()
 		{
 			status = false;
@@ -65,20 +82,34 @@ class SemanticTest: public SolidityExecutionFramework, public TestCase
 		}
 	};
 
+	/// Instantiates a test file parser that parses the additional comment section at the end of
+	/// the input stream \param _stream. Each function call is represented using a `FunctionCallTest`
+	/// and added to the list of call to be executed when `run()` is called.
+	/// Throws if parsing expectations failed.
 	void parseExpectations(std::istream& _stream);
+
+	/// Compiles and deploys currently held source.
+	/// Returns true if deployment was successful, false otherwise.
 	bool deploy(std::string const& _contractName, u256 const& _value, bytes const& _arguments);
 
-	void printFunctionCall(std::ostream& _stream, FunctionCall const& _call, std::string const& _linePrefix = "") const;
-	void printFunctionCallTest(
+	/// Prints a formatted and highlighted function call used for visual feedback in isoltest.
+	void printFunctionCallHighlighted(
+		std::ostream& _stream,
+		FunctionCall const& _call,
+		std::string const& _linePrefix = ""
+	) const;
+
+	/// Prints a formatted and highlighted function call test used for visual feedback in isoltest.
+	/// If \param _printExpected is true, it prints the expected result instead of the actual result.
+	void printFunctionCallTestHighlighted(
 		std::ostream& _stream,
 		FunctionCallTest const& test,
-		bool _expected,
+		bool _printExpected,
 		std::string const& _linePrefix = "",
 		bool const _formatted = false
 	) const;
 
 	std::string m_source;
-	std::map<std::string, dev::test::Address> m_libraryAddresses;
 	std::vector<FunctionCallTest> m_tests;
 };