The basis for the module is the arrange-act-assert model of testing. First we arrange the things we’re going to test: set up data structures or whatever you need for testing. Then we act on them: we perform the actual test steps. Finally, we assert the expected output of the test. Normally, the expectation is that during the assert step we’ll return $false if the test failed, and that’s all there is to it. Of course, there’s plenty more to testing, but lets move on to my new module.

The module is called PSaint (pronounced “saint”), and it stands, loosely, for PowerShell Arrange-Act-Assert in testing. Of course, what it stands for isn’t important, just remember the name is PSaint

PSaint is really a very simple module, with only a few functions. There are two major functions which we’ll discuss in detail: Test-Code and New-RhinoMock, and then a few helpers which you may or may not even use:

Set-TestFilter

Sets filters (include and/or exclude) for the tests by name or category.

Set-TestSetup (alias “Setup”)

Sets the test setup ScriptBlock which will be run before each test.

Set-TestTeardown (alias “Teardown”)

Sets the test teardown ScriptBlock which will be run after each test.

Assert-That

Assserts something about an object (or the output of a scriptblock) and throws if that assertion is false. This function supports asserting that an exception should be thrown, or that a test is false … and supports customizing the error message as well.

Assert-PropertyEqual

This is a wrapper around Compare-Object to compare the properties of two objects.

How to test with PSaint: Test-Code

Test-Code (alias “Test”) is the main driver of functionality in PSaint, and you use it to define the tests that you want to run. Let’s jump to an example or two so you can see the usefulness of this module.

Let’s start with an extremely simple function that we want to write: New-Guid. We want a function that generates a valid random GUID as a string. We’ll start by writing a couple of tests. First we’ll test that the output of the function is a valid GUID.

Now, to verify that the test works, you should define this function (the GUID-looking thing is one letter short) and then run that test:

Another proof that it works would be that it should fail on this function too, because “x” is not a valid character in a Guid:

So, let’s write a minimal New-Guid that actually generates a valid Guid:

If you run our test on that, you will see:

If you don’t like the fact that the Category is empty, you could add a category or two to the end of our test. We should also switch to using Assert-That if we want to know which test in the assert failed. Finally, we want to write another test which would test that New-Guid doesn’t just return the same Guid every time, the way ours does right now:

Now, we have to actually fix our New-Guid function to generate real random Guids:

And at that point, we should have a function, and a couple of tests that verify it’s functionality…

The finer points of assertions

One thing you’ll notice the first time you use Get-Member after loading the PSaint module is a few script properties have been added to everything. I did this because I found myself writing the same Assert-That calls over and over and decided that it would be slicker to make these extension methods than to write new functions for each one:

There’s also a MustThrow([Type]$Expected, [string]$Message) which can be used on script blocks (note that this function executes the ScriptBlock immediately, so be careful how you use it).

We can use these to tidy up our tests quite a bit, while still getting good error messages when tests fail:

COM Objects

PSaint also has a wrapper for COM objects to help with testing them. It adds GetProperty and SetProperty methods to allow you to access COM object properties which don’t show up on boxed COM objects (a common problem when working with MSOffice, for instance). It also adds InvokeMethod for COM objects to invoke methods that don’t show up for similar reasons. These, of course, only help you if you’re already fairly literate with the COM object in question.

Mock Objects

PSaint includes New-RhinoMock, a function for generating a new mock object using RhinoMocks (which is included). Rhino Mocks is a BSD-licensed dynamic mock object framework for the .Net platform. Its purpose is to ease testing by allowing the developer to create mock implementations of custom objects and verify the interactions using unit testing.

I have to admit that this New-RhinoMock function is incomplete, and exposes only a fraction of the options and power in RhinoMocks, but it’s been sufficient for the few times when I’ve wanted to actually mock objects from PowerShell, so I’m including it here.

For those of you (developers) who want to know why RhinoMocks instead of your favorite mocking framework, the answer is astonishingly simple: it had the least number of necessary generic methods (which are impossible to call in PowerShell 2).

The original VBScript is about 68 lines of code, and writes one event per log file. We duplicated it’s functionality with the following 11 lines of code:

Actually, even that first attempt extended the functionality a little, because we potentially make multiple archive copies which we only delete once they pass the archive date.

New-EventLog Application Robocopy

There are two catches. First, you need PowerShell 2.0. Second, before you can run that script the first time, you have to create the “Robocopy” event source for the machine by running this command in an elevated PowerShell console (that is, you have to run it “as Administrator”):

Of course, being a good geek, I couldn’t leave well enough alone, so we changed the script so that it would log each unique error to the event log (including the line following the error, which has more details), so that there’s no need to go “check the log file” on the machine, since you can retrieve the event logs remotely. The finished script looks like this:

Notice that we cleaned up the parameters a little bit, and put some defaults in, but we still haven’t written “help” ... that’s partly because I still am not sure that’s the best option for logging Another way would be to just write one log event, but with details about the errors like:

While I was playing with the source and tweaking things a little bit to improve the way it handles namespaces, I started playing with the idea that I could improve the syntax. At the very least, I thought, I ought to be able to do away with all those “xe” aliases…

Well, I was able to. ( new version) And what’s more, I managed to dramatically clean up the way namespaces work, and make it so that really, the only ugly part of the syntax is the initial declaration of namespaces! I’m going to start with two examples, and use them to walk you through the features

Example 1

The simplest example I could think of is to list all the files in a folder, with the file size and last modified stamp:

The output of that, when run on my formats folder, looks like this:

You can immediately see what the script does: New-XDocument (which is aliased as ‘xml’) actually generates the root xml node, so the first argument to it is the name of that node, and any other arguments become attributes … except for the script block. That script block turns into the contents of the node.

Inside the script block, PowerShell code is parsed as usual, but whenever a command that doesn’t exist is encountered, it is turned into an xml node! Pretty simple, right? Of course, if you wanted to create a node with a name that’s already taken by a PowerShell command, you can just replace file with New-XElement file, or (using aliases) xe 'file', which explicitly creates an xml node with the given name.

That’s pretty much it for our first example, so let’s look at a more complicated example, with multiple namespaces, and deeper nesting.

Example 2

This time, we’ll create an Atom document, and we’ll include some namespace extensions (including a made up one for listing my files as we did above):

There are four things you should notice, in particular:

First: the initial tag has a [XNamespace] added to it. You can specify a tag name that has a namespace by adding them together this way, or by embedding the namespace in the string like "{http://www.w3.org/2005/Atom}feed" instead. Either way works. This initial namespace becomes the default namespace for the document. If you don’t specify a namespace on tags later, they automatically belong to that one.

Second: when you want to add additional namespaces, you can do so with a custom prefix like: -dc ([XNamespace]"http://purl.org/dc/elements/1.1"), and that prefix (dc) takes on a special meaning. When you want to have a tag later on that is part of that namespace, you just prefix the tag, like dc:rights —the same way you would in XML.

Third: any number of attributes can be specified using the -name value syntax, but anything in a {scriptblock} becomes the content — and is subject to the same rules as the outer sections.

Fourth: This generates an XDocument. When you cast an XDocument to string, the xml declaration is left off, so if you want it, you need to manually add it via $XDocument.Declaration. Incidentally, XDocuments are not XMLDocuments, but they are trivially castable to them.

The output of that particular section of New-XDocument is this:

The New-XDocument script itself is on PoshCode in the Xml Module 4 along with a few interesting functions like Select-XML (which improves over the built-in by being able to ignore namespaces when you write XPath) and Remove-XmlNamespace (which was instrumental in removing namespaces for Select-Xml). There’s also a Format-Xml for pretty-printing, and a Convert-Xml for processing XSL transformations.

I’ll probably post some more examples of this in the next week or two, and I really should write some commentary about the function itself, which uses the tokenizer to discover which “commands” are really xml nodes … but for now, I’ll leave you to enjoy.

Related articles by Zemanta

• JSON from PowerShell (but why?) (huddledmasses.org)
• What’s in a Namespace (apache.sys-con.com)
• Ignoring Namespaces in XPath (huddledmasses.org)

The initial question is: would you attend a weekly (or monthly) virtual brown-bag lunch if I put one together.

The idea is that we would start each session with a short collection of interesting links, tips and tricks, or connect issues, and then have a presentation or discussion or script club or open-mic session, depending on interest.

Basically, this is meant to flow, on a week-to-week basis, from script-club to formal user group presentations.

Some weeks we would have presenters from various local user groups share content they had prepared for their local groups. We would encourage you to take ownership of this time, request topics, and prepare presentations (no matter how short).

Some weeks we would have an open-format script club using our private pastebin, IRC channel, and LiveMeeting voice chat. This time could vary from real-world problem solving to scripting games and “project Euler”-style challenges.

Some weeks we would have open-mic time and solicit feedback for the PowerShell team from anyone who cared to give it. I would make an effort to make sure I wasn’t the only MVP there, so you could feel that even if there wasn’t a Microsoft employee present on a given day, your voice could be heard when you make suggestions or vent frustrations …

The point is: the format would vary a bit, and we would adjust it over time to fit whatever works the best within our virtual meeting and time constraints.

So, what do you think? Are you interested?

Anyway, on to the Aero Peek stuff. If you haven’t seen it, Aero Peek is a feature of Windows 7, which lets you get a peek at your desktop, or at a single window for a moment. Basically, you can press Win+Space (the Windows logo key and the space bar) and all of your open windows instantly turn transparent, revealing … whatever was on your desktop: wallpaper, icons, and gadgets. You can also use it by hovering your mouse on the right corner of the taskbar, or you can peek at a single window by hovering over it’s taskbar button and then over it’s thumbnail.

In any case, I have a couple of windows which I would like to have stay visible on the desktop when I hit the aero peek hotkey: Rainlendar and Miranda. It turns out there’s a simple API call for this: DwmSetWindowAttribute which lets you set the DWMWA_EXCLUDED_FROM_PEEK attribute to ENABLED … causing a window to no longer hide when you press that hotkey. Of course, that API call should be made by those apps, in response to a user setting (so I’ve told their authors about it), but it doesn’t have to be (so I wrote a script to do it myself).

In the old days, I would have written a little systray app which would give you a popup list of all windows, or perhaps added a menu item to a window’s right-click menu … and I would have had to deal with creating some way to persist which apps you wanted to apply this to, and then I could have applied the setting to them whenever you opened them.

But now, I have PowerShell. I don’t need to give you menus and store settings, because I can just let you edit a little script instead.

So here’s a script which will let you turn off Aero Peek transparency for windows by window title and/or process name … Once you have this function available, you can keep Rainlendar’s calendar, tasks, and event windows all visible by just running Remove-AeroPeek -Process Rainlendar2 or you can keep your Miranda contact list visible by running Remove-AeroPeek "Miranda IM" (although you should not that depends on the window title matching just that one window — and Miranda lets you change what your title is, so you may have to adjust it).

Of course, that script really deserves explanation, because it’s showing off quite a few advanced things…

The first thing is that I’m using a Try/Catch block in the BEGIN block to make sure I only execute that code once. You can’t call Add-Type with the same code multiple times in a single PowerShell session, because the type will already exist when you call it the second time. So the code in the try block will throw an exception if the type doesn’t already exist, and in the catch handler, we’ll create the type, and define the other function we need.

Add-Type is a super-powerful cmdlet which compiles code on the fly (or imports types from pre-compiled assemblies). In this case we’re using it to import a little class called Dwm which I started writing myself from PInvoke.net and the MSDN documentation, but then eventually copied most of from a NeoWin forum thread… All this class really does is define the API function and the flags we need to pass to it, and then provides a wrapper for the DwmSetWindowAttribute call. We could have written that call in PowerShell, but at the end of the day, once you start compiling C# code in PowerShell, it’s hard to know when to stop

The Select-Window function is (yet another customized version of) a function I wrote awhile back on PoshCode as part of my (still in progress) rewrite of WASP to use the UIAutomationClient … I’ve just modified it to add only the three properties of the window that I’m interested in: Title and ProcessId (for identifying the correct windows) and Handle (for passing to the DwmSetWindowAttribute call). It uses the RootElement property of System.Windows.Automation.AutomationElement to do a search, and then a series of GetCurrentPropertyValue calls to determine the Name, ProcessId, and NativeWindowHandle of the windows it finds.

That’s pretty much all there is to it, other than filtering out the window(s) that we want and actually calling the API. I think I’m going to have to play a little bit more with this to see what else we can do — I’ve already realized that this means we can make little widgets with PowerBoots and set them to stick around just like regular desktop gadgets …

This new version is a true PowerShell 2.0 only module, because I found that the Growl callbacks can only be handled in PowerShell 2.0 anyway, so in order to add support for that, I went ahead and upgraded the rest.

The Growl module is now designed to be used BY your PowerShell scripts and modules. The idea is that if you wrote, say, a script/module to check for email and called it PoshMail … you could start up Growl like this:

Now, technically that’s all we have to do. At that point, we could pop up Growl notices for either Hotmail or GMail … let’s say our fictitious script (which is running in the background on an event timer) discovers a new message … you could notify the user with a Url callback. Let’s assume that you have a few variables set after checking for email:

• $Number is the number of email messages
• $Subjects is an array of email subject lines

• $Urls is an array of links to the emails

Of course, if you wanted to launch your Outlook 2010 preview because you discovered new POP or IMAP mail … or because you want to use Outlook to read your Hotmail/GMail … then a callback URL isn’t going to cut it. In that case, you want to handle the click event yourself:

Something like that should work regardless of your actual email client, and then you just have to pass a callback value to make sure your function gets called:

There are a lot of other possibilities here, from alerting when long running commands finish (think PSJobs, or even remote jobs) to … writing popup-based PowerShell instant messengers, or even … using Growl as a ghetto inter-process communication medium which works on multiple PCs. Ok, that’s maybe a bit much, but the point is: sky’s the limit. Have a little fun. Note that the machine SENDING the popups doesn’t necessarily have to have Growl installed — you could just copy the libraries over and then send remote growls….

This is just a quick post (as I promised, recently) to let you all know that I’ve published the first release of my Growl for Windows module for PowerShell over on PoshCode.

I haven’t been able to get callbacks to work, and I spent way too much time playing with them instead of publishing this, or working on remote growls … but nonetheless, it’s sufficient to let you pop up growl notifications from scripts, which you can, of course, customize in Growl itself.

You can add a few additional notice types very simply (you just hard code them in the script, copying lines 19 and 21 — remember you need to use the same notice names each time anyway) ... and then tweak them in Growl to have different display types, or to make some of your notice types sticky, or have them forwarded to your iPhone or whatever.

Here’s the first version of the script:

Note: if you want to use this on PowerShell 1.0, just comment out the [Parameter( lines, and dot-source it, it should work fine. In PowerShell 2.0 you’ll want to load it as a module, because doing so will hide some of those ugly script variables.

• Have you played with ZWave or X10 home automation and thought that voice control of your devices would be an obvious next step?

Well, ok … I’m not going to show you how to turn on lights or work with home automation — but that’s the main thing that keeps me thinking about this voice-recognition stuff. What geek doesn’t want to walk into the living room and say “Computer: Lights On” and have it work?

Instead, as a first step to all of that, let me show you how to use PowerShell to do simple voice command recognition scripts … which can fire off any PowerShell script you care to write! The code which follows is really a module, although you can just dot-source it as a script, and it really requires PowerShell 2.0 for the events, although it would be trivial to refactor it to work on PowerShell 1.0 using Oisin’s PSEventing library.

There’s basically just one function you need to worry about here: New-VoiceCommands. You pass it a hashtable which maps strings to scriptblocks, and if you use the -Listen switch that’s all there is to it. You can also call Start-Listening manually, and of course, I’ve provided the Say function to make it easier to have the computer speak…

Once the computer is “listening” ... you just say it’s name, followed by one of your commands. I like that because it ensures that I don’t run the scripts by accident, but you can remove the "${Env:ComputerName}, " string from the beginning of the GrammarBuilder if you think it’s not necessary, or you can hard code it to something other than your computer’s name, like say “Hal, please, I beg you … “ or “Computer, please “ or whatever.

You can do a lot of things with this … anything, really … but to give you an example that you can easily understand, I’m going to do something very simple, and have my computer just answer a few basic questions by talking back to me, and then add a few commands to have it start an app or a web page.

You see how easy that is? You can use “Say” to speak any text (although sometext will get better results than others), and you can invoke any other powershell commands, including HttpRest commands to fetch web data, or WASP commands for windows automation, or PowerBoots commands to display output in large text, or cmdlets to control X10 or ZWave devices … you know, anything

The first part of it is a WatiN script (that automates your browser) called New-ImaginaryFriend which takes three parameters: a name for the imaginary friend, a url for an avatar for the friend, and a HashTable… Of course, we sort-of cheat by using the HashTable … it’s basically a bunch of key-value pairs of remote services and user names. You can use it to add twitter ID’s like twitter="jsnover" or blogs like blog="http://HuddledMasses.org/" etc. You can even add multiple sources (eg: twitter + diigo, two blogs, etc) to a single new imaginary friend ...

This script is done using WatiN because the FriendFeed API doesn’t support creating imaginary friends yet, and as a result it’s slow, and requires IE (and doesn’t seem to work very well with IE8 — at least, I couldn’t get it to set the avatars using IE 8 on Windows 7, so I commented out the avatar part of the next-to-last line).

The other part of the script is a pair of functions: the first is Get-FriendFeedFriends which retrieves profile information for all your friends in a slick format that includes all their services and such … you may find other uses for this later , the second is Get-TwitterFriends … Both have an -Exclude parameter so you can pass it a list of people to ignore.

When you put these three functions together, you can just import the FriendFeed module, and start creating friends (don’t forget this version of the scripts only works with IE6 or IE7 for the purpose of avatars, as WatiN can’t seem to set the file upload value in IE8 yet).

You can download all of the required modules at once (7z), or grab the latest versions of them from PoshCode: FriendFeed, HttpRest, and WatiN … but if you do that, you’ll still need to get the binaries separately

Someone asked (on Twitter) about using WatiN from PowerShell, and pointed to this old post by Scott Hanselman saying he was having the same problems … so I wrote this to help them out:

WatiN requires -STA mode

Note: WatiN requires Single Threaded Apartment mode, so you need to be using PowerShell 2.0 (currently in CTP3) in order for any of this to work, and you need to pass the -STA parameter to PowerShell. Regardless, I thought I’d throw two tips out here:

Don’t use LoadFile, use LoadFrom

I’m not 100% sure when it’s appropriate to use LoadFile in PowerShell, but I can tell you that if your assembly is in a folder with a bunch of other assemblies upon which it depends … you need to use [Reflection.Assembly]::LoadFrom( $path ) instead — because the .net loader will be able to find the dependencies.

Generate some functions to help yourself out

It’s trivial to do code-generation in PowerShell, and WatiN is not friendly to the PowerShell syntax, so you’re going to want to generate a bunch of them. To get you started, here’s a set of Find-* functions to let you find each type of element that WatiN recognizes and automates… by name, id, class, style … well, by any attribute, really:

With just that little bit of code, I generated all of these functions:

• Find-Area
• Find-Button
• Find-CheckBox
• Find-Div
• Find-Element
• Find-FileUpload
• Find-Form
• Find-Image
• Find-Label
• Find-Link
• Find-Para
• Find-RadioButton
• Find-SelectList
• Find-Span
• Find-Table
• Find-TableBody
• Find-TableCell
• Find-TableRow

• Find-TextField

And each function takes the name of an attribute, like say: Alt, Class, For, Id, Index, Name, Src, Style, Text, Title, Url, Value … or just “Element” ... and a regular expression to match against the value of that attribute, and finds the control(s) that match. So for instance … since I’ve got a browser open to Google, I could trigger a search for my name by just doing:

Drat, the lawyer and that pottery guy still beat me out, maybe I should stop using “Jaykul” everywhere and start using my real name more …

Edit: Another example

Someone asked in the comments about how to parse a table, and I thought I’d post an example, because it’s pretty cool how well PowerShell works for stuff like this. Lets say I wanted to scan down a column in a table, and depending on the values, return a value from another column. For an example, I’ll take a table off Wikipedia which lists multi-protocol IM clients, and try to return the names of the clients which support IRC.

Clearly WatiN needs to fix the missin <th> TableHeader problem, but other than that, this wasn’t too painful. Of course, it would be a lot easier if we could cast ScriptBlocks as the generic Predicate<T> that the various .Find methods accept, but if I try this, it just freezes up and never returns:

Future Work

You could easily take this a lot further: dump those functions into a file for reusing next time (so you don’t have to regenerate them each time), and in fact, it would be relatively simple to make functions for each of the methods on each of the types we found above, so you would have a Click-Button function, and a TypeText-TextField function which could take those same search parameters (attribute and regular expression) and you could even generate appropriate parameters to take, for example, the text to type. In fact, you could generate a whole DSL for yourself … this guy did it using MGrammar … but why not PowerShell.