Merge pull request #717 from carolynvs/expect-multiple-commands

Add testing page for mixin developers

cmd/porter/mixins.go

@@ -127,7 +127,7 @@ bin/
     ├── mymixin-linux-amd64
     └── mymixin-windows-amd64.exe
 
-See https://porter.sh/mixin-distribution more details.
+See https://porter.sh/mixin-dev-guide/distribution more details.
 `,
 		Example: `  porter mixin feed generate
   porter mixin feed generate --dir bin --file bin/atom.xml --template porter-atom-template.xml`,

docs/config.toml

@@ -242,25 +242,31 @@ defaultContentLanguage = "en"
   weight = 350
   [[menu.main]]
     name = "Overview"
-    url = "/mixin-dev-guide"
+    url = "/mixin-dev-guide/"
     identifier = "mixin-dev-guide"
     weight = 351
     parent = "developing-mixins"
   [[menu.main]]
     name = "Commands"
-    url = "/mixin-commands"
+    url = "/mixin-dev-guide/commands/"
     identifier = "mixin-commands"
     weight = 353
     parent = "developing-mixins"
+  [[menu.main]]
+    name = "Testing"
+    url = "/mixin-dev-guide/testing/"
+    identifier = "mixin-testing"
+    weight = 355
+    parent = "developing-mixins"
   [[menu.main]]
     name = "Mixin Architecture"
-    url = "/mixin-architecture"
+    url = "/mixin-dev-guide/architecture/"
     identifier = "mixin-architecture"
     weight = 360
     parent = "developing-mixins"
   [[menu.main]]
     name = "Distributing Mixins"
-    url = "/mixin-distribution"
+    url = "/mixin-dev-guide/distribution/"
     identifier = "mixin-distribution"
     weight = 361
     parent = "developing-mixins"

docs/content/architecture-buildtime.md

@@ -17,7 +17,7 @@ if you would like to add content for this page.
 # Next
 
 * [Dependencies](/dependencies/)
-* [Mixin Architecture](/mixin-architecture/)
+* [Mixin Architecture](/mixin-dev-guide/architecture/)
 * [Building the Invocation Image](/build-image/)
 
 [contrib]: https://github.com/deislabs/porter/blob/master/CONTRIBUTING.md#documentation

docs/content/cli/mixins_feed_generate.md

@@ -25,7 +25,7 @@ bin/
     ├── mymixin-linux-amd64
     └── mymixin-windows-amd64.exe
 
-See https://porter.sh/mixin-distribution more details.
+See https://porter.sh/mixin-dev-guide/distribution more details.
 
 
 ```

docs/content/mixin-dev-guide/_index.md

@@ -0,0 +1,14 @@
+---
+title: Developing Mixins
+description: Creating and Extending Mixins for Porter
+layout: single
+---
+
+The easiest way to make a mixin right now is to use start from our template repository:
+
+<https://github.com/deislabs/porter-skeletor>
+
+## See Also
+* [Mixin Commands](./commands/)
+* [Mixin Architecture](./architecture/)
+* [Mixin Distribution](./distribution/)

docs/content/mixin-dev-guide/testing.md

@@ -0,0 +1,51 @@
+---
+title: Testing a Mixin
+description: How to test a Porter mixin
+---
+
+We are working on filling this doc out more, until then this is more of a FAQ than a proscriptive guide. If you have
+a tip, please submit a PR and help us fill this out!
+
+## How do I unit test that my mixin is executing the right commands?
+
+Here is a [full working example][example] of a unit test that validates the commands executed by a mixin.
+
+Make sure that your package has a `TestMain` that calls `github.com/deislabs/porter/pkg/test.TestMainWithMockedCommandHandlers`
+
+```go
+import "github.com/deislabs/porter/pkg/test"
+
+func TestMain(m *testing.M) {
+	test.TestMainWithMockedCommandHandlers(m)
+}
+```
+
+Then you instantiate your mixin in test mode (the skeletor template generates this method for you):
+
+```go
+m := NewTestMixin(t)
+```
+
+This sets up your test binary to assert that expected command(s) were called. You tell it what command to expect with
+
+```go
+os.Setenv(test.ExpectedCommandEnv, "helm install")
+defer os.Unsetenv(test.ExpectedCommandEnv)
+```
+
+If your mixin action executes multiple commands, separate them with a newline `\n` like so
+
+```go
+os.Setenv(test.ExpectedCommandEnv, "helm install\nhelm upgrade")
+```
+
+Now execute your mixin action:
+
+```go
+err = m.Execute()
+```
+
+Instead of os calls to the real commands, the test mixin mode calls back into your test binary. The `TestMain` handles
+asserting that the expected commands were made and fails the test if they weren't.
+
+[example]: https://github.com/deislabs/porter-gcloud/blob/v0.2.1-beta.1/pkg/gcloud/execute_test.go

docs/content/using-mixins.md

@@ -15,6 +15,6 @@ if you would like to add content for this page.
 
 # Next
 
-* [Mixin Architecture](/mixin-architecture/)
+* [Mixin Architecture](/mixin-dev-guide/architecture/)
 
 [contrib]: https://github.com/deislabs/porter/blob/master/CONTRIBUTING.md#documentation