Improve test coverage for code scanning APIs

Author: wwong

src/main/java/org/kohsuke/github/GHCodeScanningAlert.java

@@ -7,6 +7,9 @@
 import java.net.URL;
 import java.util.Date;
 
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
 /**
  * Code scanning alert for a repository
  *
@@ -142,74 +145,106 @@ public URL getHtmlUrl() throws IOException {
     @SuppressFBWarnings(value = { "UWF_UNWRITTEN_FIELD" }, justification = "JSON API")
     static class Rule {
         private String id;
-        private String severity;
-        private String description;
         private String name;
-        private String full_description;
+        private String description;
+        private String severity;
+        private String security_severity_level;
         private String[] tags;
+        private String full_description;
         private String help;
 
+        private String help_uri;
+
         /**
-         * Id of rule
+         * A unique identifier for the rule used to detect the alert.
          *
          * @return the id
          */
+        @Nullable
         public String getId() {
             return id;
         }
 
         /**
-         * Severity of rule
+         * The name of the rule used to detect the alert.
+         *
+         * @return the name
+         */
+        public String getName() {
+            return name;
+        }
+
+        /**
+         * The severity of the alert.
          *
          * @return the severity
          */
+        @Nullable
         public String getSeverity() {
             return severity;
         }
 
         /**
-         * Description of rule
+         * The security severity of the alert.
+         *
+         * @return the security severity
+         */
+        @Nullable
+        public String getSecuritySeverityLevel() {
+            return security_severity_level;
+        }
+
+        /**
+         * A short description of the rule used to detect the alert.
          *
          * @return the description
          */
+        @Nonnull
         public String getDescription() {
             return description;
         }
 
         /**
-         * Name of rule
+         * A set of tags applicable for the rule.
          *
-         * @return the name
+         * @return the tags
          */
-        public String getName() {
-            return name;
+        @Nullable
+        public String[] getTags() {
+            return tags;
         }
 
+        // The following fields only appear on some endpoints.
+        // These might be empty on endpoints like listSecurityAlerts
+
         /**
          * Full description of rule
          *
          * @return the full description
          */
+        @Nonnull
         public String getFullDescription() {
             return full_description;
         }
 
         /**
-         * Tags associated with the rule
+         * Help text for the rule
          *
-         * @return the tags
+         * @return the help text
          */
-        public String[] getTags() {
-            return tags;
+        @Nullable
+        public String getHelp() {
+            return help;
         }
 
         /**
-         * Help text for the rule
+         * A link to documentation for the rule used to detect the alert. Can be null.
          *
-         * @return the help text
+         * @return alert documentation url
          */
-        public String getHelp() {
-            return help;
+        @Nullable
+        public String getHelpUri() {
+            return help_uri;
         }
     }
 

src/main/java/org/kohsuke/github/GHCodeScanningAlertInstance.java

@@ -5,6 +5,7 @@
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
+import java.util.Objects;
 
 /**
  * Code scanning alert instance for a repository
@@ -93,41 +94,129 @@ public Location getLocation() {
         return location;
     }
 
+    @Override
+    public boolean equals(Object o) {
+        if (this == o)
+            return true;
+        if (o == null || getClass() != o.getClass())
+            return false;
+        GHCodeScanningAlertInstance that = (GHCodeScanningAlertInstance) o;
+        return Objects.equals(ref, that.ref) && Objects.equals(analysis_key, that.analysis_key)
+                && Objects.equals(environment, that.environment) && state == that.state
+                && Objects.equals(commit_sha, that.commit_sha) && Arrays.equals(classifications, that.classifications)
+                && Objects.equals(message, that.message) && Objects.equals(location, that.location);
+    }
+
+    @Override
+    public int hashCode() {
+        int result = Objects.hash(ref, analysis_key, environment, state, commit_sha, message, location);
+        result = 31 * result + Arrays.hashCode(classifications);
+        return result;
+    }
+
+    /**
+     * Alert message
+     */
     @SuppressFBWarnings(value = { "UWF_UNWRITTEN_FIELD" }, justification = "JSON API")
-    static class Message {
+    public static class Message {
         private String text;
 
+        /**
+         * Alert message
+         *
+         * @return contents of the message
+         */
         public String getText() {
             return text;
         }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o)
+                return true;
+            if (o == null || getClass() != o.getClass())
+                return false;
+            Message message = (Message) o;
+            return Objects.equals(text, message.text);
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(text);
+        }
     }
 
+    /**
+     * Describe a region within a file for an alert.
+     */
     @SuppressFBWarnings(value = { "UWF_UNWRITTEN_FIELD" }, justification = "JSON API")
-    static class Location {
+    public static class Location {
         private String path;
         private long start_line;
         private long end_line;
         private long start_column;
         private long end_column;
 
+        /**
+         * Path to the file containing the described code region
+         *
+         * @return path
+         */
         public String getPath() {
             return path;
         }
 
+        /**
+         * Line number at the start of the code region.
+         *
+         * @return line number at the start of the code region
+         */
         public long getStartLine() {
             return start_line;
         }
 
+        /**
+         * Line number at the end of the code region.
+         *
+         * @return line number at the end of the code region
+         */
         public long getEndLine() {
             return end_line;
         }
 
+        /**
+         * Column number at the start of the code region.
+         *
+         * @return column number at the start of the code region
+         */
         public long getStartColumn() {
             return start_column;
         }
 
+        /**
+         * Column number at the end of the code region.
+         *
+         * @return column number at the end of the code region
+         */
         public long getEndColumn() {
             return end_column;
         }
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o)
+                return true;
+            if (o == null || getClass() != o.getClass())
+                return false;
+            Location location = (Location) o;
+            return start_line == location.start_line && end_line == location.end_line
+                    && start_column == location.start_column && end_column == location.end_column
+                    && path.equals(location.path);
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(path, start_line, end_line, start_column, end_column);
+        }
     }
 }

src/main/java/org/kohsuke/github/GHRepository.java

@@ -3513,6 +3513,11 @@ public GHTagObject createTag(String tag, String message, String object, String t
 
     /**
      * Lists the code scanning alerts of this repository.
+     * <p>
+     * See: <a href=
+     * "https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28#list-code-scanning-alerts-for-a-repository">List
+     * code scanning alerts for a repository</a>
+     * </p>
      *
      * @return the paged iterable
      */
@@ -3522,6 +3527,11 @@ public PagedIterable<GHCodeScanningAlert> listCodeScanningAlerts() {
 
     /**
      * Lists the code scanning alerts of this repository filtered on the alert status
+     * <p>
+     * See: <a href=
+     * "https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28#list-code-scanning-alerts-for-a-repository">List
+     * code scanning alerts for a repository</a>
+     * </p>
      *
      * @param state
      *            alert status to filter on
@@ -3533,6 +3543,11 @@ public PagedIterable<GHCodeScanningAlert> listCodeScanningAlerts(GHCodeScanningA
 
     /**
      * Lists the code scanning alerts of this repository filtered on the code scanning tool name
+     * <p>
+     * See: <a href=
+     * "https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28#list-code-scanning-alerts-for-a-repository">List
+     * code scanning alerts for a repository</a>
+     * </p>
      *
      * @param toolName
      *            name of code scanning tool that creates alerts
@@ -3550,6 +3565,12 @@ private PagedIterable<GHCodeScanningAlert> listCodeScanningAlerts(Map<String, Ob
     /**
      * Get code scanning alert by id
      *
+     * <p>
+     * See: <a href=
+     * "https://docs.github.com/en/rest/code-scanning/code-scanning?apiVersion=2022-11-28#get-a-code-scanning-alert">
+     * Get a code scanning alert</a>
+     * </p>
+     *
      * @param id
      *            id of the code scanning alert
      * @return the code scanning alert

src/test/java/org/kohsuke/github/GHCodeScanningAlertInstanceTest.java

@@ -7,8 +7,7 @@
 import java.io.IOException;
 import java.util.List;
 
-import static org.hamcrest.Matchers.greaterThanOrEqualTo;
-import static org.hamcrest.Matchers.not;
+import static org.hamcrest.Matchers.*;
 
 /**
  * <p>
@@ -21,6 +20,12 @@ public class GHCodeScanningAlertInstanceTest extends AbstractGitHubWireMockTest
     private static final String REPO_NAME = "Pixi";
     private GHCodeScanningAlert alert;
 
+    /**
+     * Load a dismissed alert from the code scanning api web response
+     *
+     * @throws Exception
+     *             the exception
+     */
     @Before
     public void setUp() throws Exception {
         GHRepository repo = gitHub.getRepository(GITHUB_API_TEST_ORG + "/" + REPO_NAME);
@@ -35,6 +40,12 @@ private GHCodeScanningAlert getAlertFromRepo(GHRepository repo) {
         return dismissedAlerts.get(0);
     }
 
+    /**
+     * Test that an alert returns a list of its own instances
+     *
+     * @throws IOException
+     *             could not get a compatible response
+     */
     @Test
     public void testListAlertInstances() throws IOException {
         // Arrange
@@ -53,13 +64,19 @@ public void testListAlertInstances() throws IOException {
         assertThat(instance.getMessage(), not((Object) null));
         assertThat(instance.getLocation(), not((Object) null));
 
+        assertThat(instance.getMessage().getText(), not(emptyOrNullString()));
+
+        assertThat(instance.getAnalysisKey(), not((Object) null));
+        assertThat(instance.getClassifications(), not((Object) null));
+        assertThat(instance.getEnvironment(), notNullValue());
+
         GHCodeScanningAlertInstance.Location location = instance.getLocation();
         // Can't assert on exact values with having to hardcode values from
         // json file, hence making the assertions generics
         assertThat(location.getPath(), not((Object) null));
         assertThat(location.getStartLine(), greaterThanOrEqualTo(0L));
         assertThat(location.getEndLine(), greaterThanOrEqualTo(0L));
         assertThat(location.getStartColumn(), greaterThanOrEqualTo(0L));
-        assertThat(location.getStartColumn(), greaterThanOrEqualTo(0L));
+        assertThat(location.getEndColumn(), greaterThanOrEqualTo(0L));
     }
 }