More test docs & a guard around future accidental uploads of empty runtime JARs

Author: mannodermaus

android-junit5-embedded-runtime/build.gradle

@@ -1,3 +1,5 @@
+import java.util.jar.JarFile
+
 buildscript {
   repositories {
     jcenter()
@@ -77,6 +79,17 @@ task copyPom(type: Copy) {
 
 publish.dependsOn copyPom
 
+def verifyJarNotEmpty = {
+  // Manually verify that the JAR file isn't "empty"
+  // before attempting the upload. This happens on accidental
+  // upload attempts without first deploying the shadowJar.
+  def jarFileName = file("$buildDir/libs/${project.name}-${VERSION_NAME}.jar")
+  def jarFile = new JarFile(jarFileName)
+  if (jarFile.getEntry("com") == null) {
+    throw new AssertionError("The embedded-runtime JAR is empty!")
+  }
+}
+
 project.configure(project) {
   if (project.version.endsWith("-SNAPSHOT")) {
     // Configure deployment of snapshot versions to Sonatype OSS
@@ -92,6 +105,8 @@ project.configure(project) {
         }
       }
     }
+    publish.doFirst verifyJarNotEmpty
+
   } else {
     // Configure deployment of release versions to Bintray
     project.bintray {
@@ -113,5 +128,7 @@ project.configure(project) {
         }
       }
     }
+
+    bintrayUpload.doFirst verifyJarNotEmpty
   }
 }

android-junit5/src/test/groovy/de/mannodermaus/gradle/plugins/android_junit5/BaseFunctionalSpec.groovy

@@ -15,6 +15,22 @@ import java.nio.file.Paths
 
 import static de.mannodermaus.gradle.plugins.android_junit5.util.StringUtils.splitClasspath
 
+/*
+ * Base class for functional tests of the plugin
+ * across different versions of the Android Gradle Plugin.
+ * It is extended inside the respective sub-configurations for
+ * Android Gradle Plugin 2 & 3, which then drive the execution
+ * of unit tests embedded in "virtual projects", as if the plugin
+ * was applied to an actual client project. To do this, there are
+ * several factory-like methods that write pieces of the build script
+ * into a temporary file and allow for a clean "given-when-then" approach
+ * to setting up those temporary projects.
+ *
+ * This class tests the runtime behaviour of
+ * the test tasks generated by the plugin,
+ * rather than the structural integrity, which is enforced by BasePluginSpec.
+ */
+
 abstract class BaseFunctionalSpec extends Specification {
 
   @Rule