Jojoba

Jojoba 4, the multi-threaded testing framework for PowerShell

View the Project on GitHub codykonior/Jojoba

Jojoba PowerShell Module by Cody Konior

Jojoba logo

Build status

Read the CHANGELOG

Description

Jojoba wraps function internals to run their pipeline inputs in parallel and output in a test format which can be understood by users, other scripts, and PowerShell. It does this by providing a simple template to follow with a few optional keywords. It’s useful for fast, simple, and reliable testing and operational validation of large server environments.

Why does it exist? Because:

Jojoba does away with all of this so you don’t need to think about it or maintain it yourself anymore. Back-end job functionality is provided by the world-class PoshRSJob runspace management module.

Please note: There are breaking changes in Jojoba 4 from previous versions of Jojoba.

Installation

Install-Module -Name Jojoba

It is written for Windows PowerShell 5.1 and has also been tested on PowerShell Core 6.0.1 for Windows. PowerShell 5.1 introduces a lot of performance fixes for the pipeline and is required to use modern tags in the PowerShell Gallery.

Example

Any function using Jojoba needs a minimum of:

Any additional function parameters not sent through the pipeline will be serialized to strings and so should be limited to simple types: ints, strings, string arrays, bools, and switches.

function Test-ComputerPing {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory, ValueFromPipeline)]
        [string] $ComputerName,

        # Your other arguments here

        [Parameter(ValueFromRemainingArguments)]
        $Jojoba
    )

    begin {
    }
    process {
        Start-Jojoba {
            #region Your code
            & ping $ComputerName -n 1
            if ($LASTEXITCODE -ne 0) {
                Write-JojobaFail "Connection failed"
            }
            #endregion
        }
    }
    end {
        Publish-Jojoba
    }
}

Demo

GIF of Jojoba function executing

Major functions

Passing parameters to Jojoba

Jojoba doesn’t take parameters directly, instead parameters are passed to your function and intercepted through parameter selected to hold RemainingArguments.

Common:

Uncommon:

Further Examples

Let’s say you have a lot of tests and you want to store the results of every test in a repository (like a database). You could do it like this:

<inputs> | <function that uses Jojoba> -JojobaPassThru | <function that writes the object to a database>

There is another way which is to use parameter -JojobaCallback which takes a function name which is passed a single test case object at a time just as if it had been given a -JojobaPassThru. You can use it like this:

<inputs> | <function that uses Jojoba> -JojobaPassThru -JojobaCallback <function that writes the object to a database>

Or better like this because it guarantees output rather than users remembering to do it:

function <function that uses Jojoba> {
    ...
    end {
        Publish-Jojoba -JojobaCallback <function that writes the object to a database>
    }
}

Another way to use it is by defining PSDefaultParameterValues in the .psm1 of your module that defines all of your test functions.

# In your module's .psm1
$PSDefaultParameterValues."Publish-Jojoba:JojobaCallback" = "Write-Callback"
# From the command line
<inputs> | <function that uses Jojoba>

The callback function should look like below, though the specific function name and parameter names are irrelevant:

function Write-Callback {
    [CmdletBinding()]
    param (
        [Parameter(ValueFromPipeline)]
        $TestCase
    )

    begin {
    }
    process {
        # Do something with $TestCase
    }
    end {
    }
}

There are a few other important things to remember with this functionality:

That’s why it’s an advanced feature. You may have to try it and work out how to get it going the first time depending on your use case.

Tips

Presentation

Watch the hour long video.

Templates have changed from what was demonstrated in that video to now. You must use the template format in this README instead. You can also read the CHANGELOG.

Also these are other changes in Jojoba 4 not presented in that video: