Improve Space homepage content (#61)

* Improve Space homepage content

Prior to this commit the Confluence Space homepage (for any Spaces that
we publish Gauge specs to) was just Confluence's default generic
homepage.  This commit updates the Confluence Space homepage to have a
useful overview of what the Space contains and why, along with links to
find out more about Gauge and this Gauge Confluence plugin.

We republish this homepage content on every run of the plugin, even
though it is just rewriting the same content each time.  This is so that
it is easy to update the homepage content in the future, if and when we
want to amend or improve it.

* Fix functional tests by updating Space name

* Set default Confluence Space key in tests

* Test that homepage is republished on every run

This commit adds a Gauge spec to verify that the Confluence Space
homepage is updated (i.e. republished by the plugin) on every run of the
plugin.

This is important as if we tried to do something "clever" such as only
updating the homepage on the first run of the plugin, we'd be stuck if
we ever want to roll out a change which modifies the content of the
homepage.

* Bump plugin minor version

* Run the CI tests just on Ubuntu

Prior to this commit we were running the CI tests on Ubuntu, Windows
and macOS.  This commit removes Windows and macOS from the CI/CD tests.
The reason for this is that having the test suite run simultaneously on
all three was sometimes causing subtle test failures, generally caused
by contention around the same Confluence Space.

Also created #62 to ensure that we run the CI tests on a schedule
(weekly?) against all 3 operating systems.

.github/workflows/functional-test.yml

@@ -40,7 +40,7 @@ jobs:
     needs: [create-and-store-binaries]
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest]
         confluence-version: [Cloud]
         include:
           - confluence-version: Cloud

functional-tests/specs/delete_specs_before_publishing.spec

@@ -1,5 +1,6 @@
 # Delete existing published specs before publishing
-Tags: create-space-manually
+
+tags: create-space-manually
 
 ## The plugin deletes all existing published specs before publishing
 It is safe to do this as before doing so we abort if the Space has been manually edited since the last publish.
@@ -18,8 +19,8 @@ plugin handles pagination correctly when deleting the specs on the second publis
 
 * Published pages are:
 
-   |title                         |parent      |
-   |------------------------------|------------|
-   |Space Home                    |            |
-   |specs                         |Space Home  |
-   |Another spec                  |specs       |
+   |title                                         |parent                                        |
+   |----------------------------------------------|----------------------------------------------|
+   |Gauge specs for example-user/example-repo Home|                                              |
+   |specs                                         |Gauge specs for example-user/example-repo Home|
+   |Another spec                                  |specs                                         |

functional-tests/specs/do_not_publish_concepts.spec

@@ -1,5 +1,6 @@
 # Concepts are not published
-Tags: create-space-manually
+
+tags: create-space-manually
 
 ## Concepts are not published
 
@@ -12,11 +13,11 @@ Tags: create-space-manually
 
 * Published pages are:
 
-   |title     |parent    |
-   |----------|----------|
-   |Space Home|          |
-   |specs     |Space Home|
-   |A spec    |specs     |
+   |title                                         |parent                                        |
+   |----------------------------------------------|----------------------------------------------|
+   |Gauge specs for example-user/example-repo Home|                                              |
+   |specs                                         |Gauge specs for example-user/example-repo Home|
+   |A spec                                        |specs                                         |
 
 
 ## A directory that just contains concepts is not published
@@ -30,11 +31,11 @@ Tags: create-space-manually
 
 * Published pages are:
 
-   |title                |parent    |
-   |---------------------|----------|
-   |Space Home           |          |
-   |specs                |Space Home|
-   |A spec in a specs dir|specs     |
+   |title                                         |parent                                        |
+   |----------------------------------------------|----------------------------------------------|
+   |Gauge specs for example-user/example-repo Home|                                              |
+   |specs                                         |Gauge specs for example-user/example-repo Home|
+   |A spec in a specs dir                         |specs                                         |
 
 
 ## Nested directories that just contain concepts are not published
@@ -51,8 +52,8 @@ Tags: create-space-manually
 
 * Published pages are:
 
-   |title                |parent    |
-   |---------------------|----------|
-   |Space Home           |          |
-   |specs                |Space Home|
-   |A spec in a specs dir|specs     |
+   |title                                         |parent                                        |
+   |----------------------------------------------|----------------------------------------------|
+   |Gauge specs for example-user/example-repo Home|                                              |
+   |specs                                         |Gauge specs for example-user/example-repo Home|
+   |A spec in a specs dir                         |specs                                         |

functional-tests/specs/homepage.spec

@@ -0,0 +1,47 @@
+# The Confluence Space homepage contains useful info
+
+## The Space homepage contains useful info after publishing, when the space was created by the plugin
+
+* Publish "1" specs to Confluence
+
+* Homepage has title "Gauge specs for example-user/example-repo Home"
+
+* Homepage contains "Do not edit this Space manually."
+
+
+## The Space homepage contains useful info after publishing, when the space was manually created
+Tags: create-space-manually
+
+* Publish "1" specs to Confluence
+
+* Homepage has title "Gauge specs for example-user/example-repo Home"
+
+* Homepage contains "Do not edit this Space manually."
+
+
+## The Space homepage is republished on every run of the plugin, when the space was created by the plugin
+
+* Publish "1" specs to Confluence
+
+The version number is 2 after the initial publish because the plugin immediately updates the homepage that
+was initially created with default content when the space was created by the plugin, on the same plugin run.
+* Homepage version number is "2"
+
+* Publish "1" specs to Confluence
+
+* Homepage version number is "3"
+
+
+## The Space homepage is republished on every run of the plugin, when the space was manually created
+
+Tags: create-space-manually
+
+* Homepage version number is "1"
+
+* Publish "1" specs to Confluence
+
+* Homepage version number is "2"
+
+* Publish "1" specs to Confluence
+
+* Homepage version number is "3"

functional-tests/specs/publish_specs.spec

@@ -1,5 +1,6 @@
 # End to end example
-Tags: create-space-manually
+
+tags: create-space-manually
 
 ## All specs are published, including those in subdirectories
 The specs are published to Confluence as a page tree, mirroring the directory structure of the specs.  This means that
@@ -16,14 +17,14 @@ as well as a Confluence page being created for each spec, a page is also created
 
 * Published pages are:
 
-   |title                         |parent      |
-   |------------------------------|------------|
-   |Space Home                    |            |
-   |specs                         |Space Home  |
-   |subfolder                     |specs       |
-   |subfolder2                    |specs       |
-   |A spec in the specs dir       |specs       |
-   |subsubfolder                  |subfolder   |
-   |A spec in the subfolder dir   |subfolder   |
-   |A spec in the subfolder2 dir  |subfolder2  |
-   |A spec in the subsubfolder dir|subsubfolder|
+   |title                                         |parent                                        |
+   |----------------------------------------------|----------------------------------------------|
+   |Gauge specs for example-user/example-repo Home|                                              |
+   |specs                                         |Gauge specs for example-user/example-repo Home|
+   |subfolder                                     |specs                                         |
+   |subfolder2                                    |specs                                         |
+   |A spec in the specs dir                       |specs                                         |
+   |subsubfolder                                  |subfolder                                     |
+   |A spec in the subfolder dir                   |subfolder                                     |
+   |A spec in the subfolder2 dir                  |subfolder2                                    |
+   |A spec in the subsubfolder dir                |subsubfolder                                  |

functional-tests/specs/space_creation.spec

@@ -10,12 +10,12 @@
 
 * Space has name "Gauge specs for example-user/example-repo"
 
-* Output contains "Success: published 2 specs and directory pages to Confluence Space named: Gauge specs for example-user/example-repo"
-
 The `example-user/example-repo` comes from the [dummy Git remote URL config in the
 test framework code][1].  When users run the plugin the Space name will be taken from 
 the Git remote URL of the Git repository that the plugin is executed on.
 
+* Output contains "Success: published 2 specs and directory pages to Confluence Space named: Gauge specs for example-user/example-repo"
+
 * Space has description "Gauge (https://gauge.org) specifications from https://github.com/example-user/example-repo, published automatically by the Gauge Confluence plugin tool (https://github.com/agilepathway/gauge-confluence) as living documentation.  Do not edit this Space manually.  You can use Confluence's Include Macro (https://confluence.atlassian.com/doc/include-page-macro-139514.html) to include these specifications in as many of your existing Confluence Spaces as you wish."
 
 ## If the Space does not already exist, the plugin needs to be run by a user with permissions to create it

functional-tests/specs/spec_validity.spec

@@ -1,5 +1,6 @@
 # Spec validity for publishing to Confluence
-Tags: create-space-manually
+
+tags: create-space-manually
 
 ## Specs without a heading are not published to Confluence
 
@@ -13,11 +14,11 @@ Tags: create-space-manually
 
 * Published pages are:
 
-   |title     |parent    |
-   |----------|----------|
-   |Space Home|          |
-   |specs     |Space Home|
-   |Spec 1    |specs     |
-   |Spec 3    |specs     |
+   |title                                         |parent                                        |
+   |----------------------------------------------|----------------------------------------------|
+   |Gauge specs for example-user/example-repo Home|                                              |
+   |specs                                         |Gauge specs for example-user/example-repo Home|
+   |Spec 1                                        |specs                                         |
+   |Spec 3                                        |specs                                         |
 
 * Output contains "Skipping file: could not find a spec heading"

functional-tests/src/test/java/com/thoughtworks/gauge/test/confluence/Confluence.java

@@ -27,9 +27,10 @@ public class Confluence {
     private static final String CONFLUENCE_USERNAME = "confluence-username";
     private static final String CONFLUENCE_TOKEN = "confluence-token";
     private static final String GIT_REMOTE_URL_KEY_NAME = "git-remote-url";
+    private static final String DEFAULT_SCENARIO_SPACE_KEY = "GITHUBCOMEXAMPLEUSEREXAMPLEREPO";
 
     public static String getScenarioSpaceKey() {
-        return Objects.toString(ScenarioDataStore.get(SCENARIO_SPACE_KEY_NAME), "");
+        return Objects.toString(ScenarioDataStore.get(SCENARIO_SPACE_KEY_NAME), DEFAULT_SCENARIO_SPACE_KEY);
     }
 
     public static String getScenarioSpaceHomepageID() {
@@ -142,6 +143,24 @@ private void assertConsoleSuccessOutput(int totalPages) throws IOException {
                 String.format("Success: published %d specs and directory pages to Confluence", totalPages));
     }
 
+    @Step("Homepage contains <content>")
+    public void assertHomepageContains(String content) throws Exception {
+        Homepage homepage = new Space(getScenarioSpaceKey()).getHomepage();
+        assertThat(homepage.getBody()).contains(content);
+    }
+
+    @Step("Homepage has title <title>")
+    public void assertHomepageHasTitle(String title) throws Exception {
+        Homepage homepage = new Space(getScenarioSpaceKey()).getHomepage();
+        assertThat(homepage.getTitle()).isEqualTo(title);
+    }
+
+    @Step("Homepage version number is <version>")
+    public void assertHomepageVersion(int version) throws Exception {
+        Homepage homepage = new Space(getScenarioSpaceKey()).getHomepage();
+        assertThat(homepage.getVersion()).isEqualTo(version);
+    }
+
     @Step("Manually add a page to the Confluence space")
     public void manuallyAddPageToConfluenceSpace() throws InterruptedException {
         // the page needs to be added at a later minute than when the last publish ran

functional-tests/src/test/java/com/thoughtworks/gauge/test/confluence/ConfluenceClient.java

@@ -117,7 +117,7 @@ private static HttpRequest getAllPagesRequest(String spaceKey) {
 
     private static HttpRequest getSpaceRequest(String spaceKey) {
         HttpRequest.Builder builder = baseConfluenceRequest();
-        String getSpaceURL = String.format("%1$s/%2$s?expand=description.plain", baseSpaceAPIURL(), spaceKey);
+        String getSpaceURL = String.format("%1$s/%2$s?expand=description.plain,homepage.body.view,homepage.version", baseSpaceAPIURL(), spaceKey);
         builder.uri(URI.create(getSpaceURL));
         return builder.build();
     }

functional-tests/src/test/java/com/thoughtworks/gauge/test/confluence/Homepage.java

@@ -0,0 +1,30 @@
+package com.thoughtworks.gauge.test.confluence;
+
+import org.json.JSONObject;
+
+public class Homepage {
+
+    private JSONObject jsonHomepage;
+
+    public Homepage(JSONObject jsonHomepage) {
+        this.jsonHomepage = jsonHomepage;
+    }
+
+    public String getTitle() {
+        return jsonHomepage.getString("title");
+    }
+
+    public String getBody() {
+        return jsonHomepage.getJSONObject("body").getJSONObject("view").getString("value");
+    }
+
+    public int getVersion() {
+        return jsonHomepage.getJSONObject("version").getInt("number");
+    }
+
+    @Override
+    public String toString() {
+        return jsonHomepage.toString(4);
+    }
+
+}

functional-tests/src/test/java/com/thoughtworks/gauge/test/confluence/Space.java

@@ -22,6 +22,10 @@ public String getDescription() {
         return jsonSpace.getJSONObject("description").getJSONObject("plain").getString("value");
     }
 
+    public Homepage getHomepage() {
+        return new Homepage(jsonSpace.getJSONObject("homepage"));
+    }
+
     @Override
     public String toString() {
         return jsonSpace.toString(4);

internal/confluence/api/client.go

@@ -35,8 +35,8 @@ func dummyClient() Client {
 	return Client{http.NewClient("", "", ""), nil}
 }
 
-// PublishPage publishes a page to Confluence as a child of the given parent page.
-func (c *Client) PublishPage(spaceKey, title, body, parentPageID string) (pageID string, err error) {
+// CreatePage publishes a page to Confluence as a child of the given parent page.
+func (c *Client) CreatePage(spaceKey, title, body, parentPageID string) (pageID string, err error) {
 	requestContent := &goconfluence.Content{
 		Type:  "page",
 		Title: title,
@@ -65,6 +65,27 @@ func (c *Client) PublishPage(spaceKey, title, body, parentPageID string) (pageID
 	return responseContent.ID, nil
 }
 
+// UpdatePage updates an existing page in Confluence.
+func (c *Client) UpdatePage(spaceKey, pageID, title, body string, version int) (err error) {
+	requestContent := &goconfluence.Content{
+		Type:  "page",
+		ID:    pageID,
+		Title: title,
+		Body: goconfluence.Body{
+			Storage: goconfluence.Storage{
+				Value:          body,
+				Representation: "wiki",
+			},
+		},
+		Space:   goconfluence.Space{Key: spaceKey},
+		Version: &goconfluence.Version{Number: version},
+	}
+
+	_, err = c.goconfluenceClient.UpdateContent(requestContent)
+
+	return err
+}
+
 // DeleteAllPagesInSpaceExceptHomepage deletes all the pages in the given Space,
 // apart from the Space home page
 func (c *Client) DeleteAllPagesInSpaceExceptHomepage(spaceKey string, homepageID string) (err error) {
@@ -154,8 +175,8 @@ func (c *Client) DoesSpaceExist(spaceKey string) (bool, error) {
 }
 
 // SpaceHomepage provides the page ID, no. of children and created time for the given Space's homepage.
-func (c *Client) SpaceHomepage(spaceKey string) (string, int, string, error) {
-	path := fmt.Sprintf("space?spaceKey=%s&expand=homepage.children.page,homepage.history", spaceKey)
+func (c *Client) SpaceHomepage(spaceKey string) (string, int, string, int, error) {
+	path := fmt.Sprintf("space?spaceKey=%s&expand=homepage.children.page,homepage.history,homepage.version", spaceKey)
 
 	var homepageResponse struct {
 		Results []struct {
@@ -169,19 +190,22 @@ func (c *Client) SpaceHomepage(spaceKey string) (string, int, string, error) {
 						Size int `json:"size"`
 					} `json:"page"`
 				} `json:"children"`
+				Version struct {
+					Number int `json:"number"`
+				}
 			} `json:"homepage"`
 		} `json:"results"`
 	}
 
 	err := c.httpClient.GetJSON(path, &homepageResponse)
 
 	if err != nil {
-		return "", 0, "", err
+		return "", 0, "", 0, err
 	}
 
 	h := homepageResponse.Results[0].Homepage
 
-	return h.ID, h.Children.Page.Size, h.History.CreatedDate, nil
+	return h.ID, h.Children.Page.Size, h.History.CreatedDate, h.Version.Number, nil
 }
 
 // IsSpaceModifiedSinceLastPublished returns true if any page was modified since the last publish