Merge pull request #17 from virtualcell/errorMessageImprovement

Add generateErrorReport for better error messages (0.0.16)

Author: jcschaff

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "libvcell"
-version = "0.0.15.4"
+version = "0.0.16"
 description = "This is a python package which wraps a subset of VCell Java code as a native python package."
 authors = ["Jim Schaff <schaff@uchc.edu>", "Ezequiel Valencia <evalencia@uchc.edu>"]
 repository = "https://github.com/virtualcell/libvcell"

vcell-native/src/main/java/org/vcell/libvcell/Entrypoints.java

@@ -14,6 +14,13 @@
 
 import java.io.File;
 import java.nio.file.Path;
+import java.util.List;
+import java.util.ArrayList;
+import java.util.Map;
+import java.util.LinkedHashMap;
+import java.util.Set;
+import java.util.Arrays;
+import java.util.stream.Collectors;
 import java.util.concurrent.ConcurrentHashMap;
 
 import static org.vcell.libvcell.ModelUtils.*;
@@ -34,6 +41,47 @@ private static CCharPointer createString(String str) {
         return ptr;
     }
 
+	// should only be externally invoked by tests!
+	public static String generateErrorReport(String topMostMessage, Throwable exceptionEncountered){
+		boolean hasNoMessage = topMostMessage == null;
+		boolean hasNoException = exceptionEncountered == null;
+		if (hasNoMessage && hasNoException) throw new IllegalArgumentException("Both arguments cannot be null");
+		if (hasNoException) return topMostMessage;
+		StringBuilder errorMessage = new StringBuilder();
+		errorMessage.append(hasNoMessage ? "VCell encountered the following error" : topMostMessage).append("\n");
+
+		List<String> exceptionTypes = new ArrayList<>();
+		List<String> stackMessages = new ArrayList<>();
+		List<StackTraceElement[]> stackTraces = new ArrayList<>();
+		Map<StackTraceElement[], Set<StackTraceElement>> stackTraceMapping = new LinkedHashMap<>();
+		Throwable cause = exceptionEncountered;
+		do {
+			exceptionTypes.add(cause.getClass().getSimpleName());
+			stackMessages.add(cause.getMessage());
+			StackTraceElement[] stack = cause.getStackTrace();
+			stackTraces.add(stack);
+			stackTraceMapping.put(stack, Arrays.stream(stack).collect(Collectors.toSet()));
+		} while (null != (cause = cause.getCause()));
+
+		errorMessage.append("Error:\n");
+		for (int i = 0; i < exceptionTypes.size(); i++) {
+			errorMessage.append(i).append(" ").repeat("-", 3 * (i + 1) - 1).append("> ");
+			errorMessage.append(exceptionTypes.get(i)).append(" :: ").append(stackMessages.get(i)).append("\n");
+		}
+		errorMessage.append("\nStack Traces:\n");
+		for (int i = exceptionTypes.size() - 1; i >= 0; i--) {
+			errorMessage.append(i).append(") ").append(exceptionTypes.get(i)).append(":\n");
+			StackTraceElement[] stack = stackTraces.get(i);
+			Set<StackTraceElement> oldStackTraceSet = i > 0 ? stackTraceMapping.get(stackTraces.get(i - 1)): Set.of();
+			for (StackTraceElement ste : stack) {
+				if (oldStackTraceSet.contains(ste)) break;
+				errorMessage.append(ste).append("\n");
+			}
+			errorMessage.append("\n");
+		}
+		return errorMessage.toString();
+	}
+
 
     @CEntryPoint(name = "freeString", documentation = "Release memory allocated for a string")
     public static void freeString(

vcell-native/src/test/java/org/vcell/libvcell/MiscTests.java

@@ -0,0 +1,53 @@
+package org.vcell.libvcell;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.vcell.libvcell.ModelUtils.vcml_to_vcml;
+
+public class MiscTests {
+
+	@Test
+	public void testErrorMessageCreation() throws IOException {
+		String vcmlContent;
+		try (InputStream is = MiscTests.class.getResourceAsStream("/bad_vcml.vcml")) {
+			Assertions.assertNotNull(is);
+			vcmlContent = new String(is.readAllBytes(), StandardCharsets.UTF_8);
+		}
+		Path ignored = Files.createTempFile("dummy", ".vcml");
+		try {
+			vcml_to_vcml(vcmlContent, ignored);
+		} catch (Exception e) {
+			String actualErrMsg = Entrypoints.generateErrorReport("Something went wrong!", e).strip();
+
+			// The report opens with the caller-supplied top-level message, followed by a structured
+			// summary of the nested cause chain. These parts are deterministic, so assert them exactly.
+			// We deliberately do NOT assert the verbatim stack-trace frames: they embed vcell-core line
+			// numbers (which drift as the submodule updates) and test-runner frames (which differ between
+			// IDE and Maven Surefire), making a full-string comparison inherently brittle.
+			Assertions.assertTrue(actualErrMsg.startsWith(EXPECTED_SUMMARY), actualErrMsg);
+
+			// A stack-trace section is appended, deepest cause first, listing real frames from the failure.
+			Assertions.assertTrue(actualErrMsg.contains("Stack Traces:"), actualErrMsg);
+			Assertions.assertTrue(actualErrMsg.contains("1) ExpressionBindingException:"), actualErrMsg);
+			Assertions.assertTrue(actualErrMsg.contains("0) XmlParseException:"), actualErrMsg);
+			Assertions.assertTrue(actualErrMsg.contains("cbit.vcell.parser.ASTIdNode.bind("), actualErrMsg);
+			Assertions.assertTrue(actualErrMsg.contains("cbit.vcell.xml.XmlReader.getSpeciesContextSpecs("), actualErrMsg);
+			Assertions.assertTrue(actualErrMsg.contains("org.vcell.libvcell.ModelUtils.vcml_to_vcml("), actualErrMsg);
+			return;
+		}
+		throw new IllegalStateException("An exception was not thrown when one should have been!");
+	}
+
+	private static final String EXPECTED_SUMMARY = """
+Something went wrong!
+Error:
+0 --> XmlParseException :: Error setting Velocity parameter for 'H3
+1 -----> ExpressionBindingException :: 'norm_X' is either not found in your model or is not allowed to be used in the current context. Check that you have provided the correct and full name (e.g. Ca_Cytosol).""".strip();
+
+}