One of my main annoyances with WebOS is that it can be really difficult to figure out why an element is displaying improperly on-screen. Up until WebOS 2, Palm provided a tool called the Palm Inspector that allowed you to use the WebKit Inspector to take a look at what was going on under your app’s skin, but it sucked for numerous reasons (first and foremost being that it didn’t work at all with apps that ran in “headless” mode—which means every app that has the capability to create new cards or dashboard stages).

As a result of this suckitude, HP deep-sixed the Palm Inspector, and it no longer works with emulators running WebOS 2.0+, leaving current WebOS developers with an interesting conundrum: how the heck do we debug WebOS 2.0 app styling problems?

Fortunately, there is a way, and its name is weinre (WEbkit REmote INspector, and pronounced “winery” or “wiener” depending on personal preference and maturity level). Weinre is basically what the Palm Inspector should have been all along: you can inspect any kind of app (headless or not), and some things (like highlighting the elements you hover over in the Inspector within the emulator) work surprisingly well. However, setting up weinre is a bit more complicated than the Palm Inspector. Here’s how to go about it on Mac OS X.

Initial setup

1. Download the Mac OS X version of weinre
2. Unzip weinre, and run it once (or you can create the hidden folder below by hand). Quit weinre; we don’t actually want it running yet.

3. Navigate to ~/.weinre/ in the Finder or Terminal.app (in the Finder, open a new window, click the Go→Go To Folder menu item, and enter that path). Using your favorite text editor (*ahem*), create a new file here called server.properties with this line as its only contents:

   boundHost:    -all-

   (If down the road you want to customize your weinre server settings further, this is the file that you will use; more detail here.)

You are now ready for weinre to work its magic!

Using weinre

When you need to use weinre to figure out why on earth your beautiful CSS isn’t behaving as you would expect, do the following:

1. Launch the Palm Emulator (obviously)

2. Open up Terminal.app, and enter this to create an SSH tunnel to the Emulator (hit enter when it queries for your password; no password needed):

   ssh -p 5522 -L 5581:localhost:8080 root@localhost
   

3. Launch weinre, and in the Debugger tab look for boundHosts under “Server Properties”. There should be something resembling either an I.P. address or using the format “computer-name.local”. This is the address that you can use from the Emulator to connect to weinre. So for instance, if your computer is named “epic-burrito”, then epic-burrito.local will be in the list.

4. In your app’s index.html file (and any other HTML files that you want to debug, like dashboard templates), add this script tag in the HEAD (assuming your computer is indeed located at epic-burrito.local):

   <script src="http://epic-burrito.local:8080/target/target-script-min.js"></script>
   

5. Install and run your app, and when you switch back to weinre you should find it in the list of targets. If you are perusing the Elements pane and notice that it isn’t up to date, try switching between different targets and back in the Debugger tab; this seemed to do the trick for me for refreshing widgets that hadn’t shown up in weinre, for instance.

Upsides and downsides

On the one hand, weinre’s WebKit Inspector is far superior to the Palm Inspector (hurray, the console is there!). On the other, the setup is a lot more onerous. Particularly nasty is the need to embed a local reference to the script tag that makes the magic happen. What I’ve done is create a folder with debugging versions of various files in my app (like sources.json), and I’ve added a copy of my index.html to that folder. Then when I need it, I copy it to the root of the project, and when I’m done testing revert the file in my Git repo.

There likely are other problems and gotchas, and I’ll update the post if I run into them; I haven’t tested weinre’s capabilities extensively by any means.

However, given that we literally have no other options (unless you count the bugtastic “Emulator host mode”, which I don’t), weinre is a pretty solid option for WebOS debugging at the moment.

Many thanks to unwiredben for the tip that led me to weinre!

Updates after further testing

You need to place the weinre <script> tag at the very top of your HEAD (before your Mojo framework include and custom CSS <link>).

One big gotcha I’m finding when working with weinre is that default Palm styles are not displayed in the “Matched CSS rules” section. The section properly shows properties in your local rules that have been overridden, and the Computed Styles section works great, but it does not display the Palm styles that are affecting your app. Best I can tell, this is because the Palm styles are included by Mojo writing out <link> tags on the fly, which doesn’t play well with weinre. This can make it difficult to debug specificity problems with your custom selectors.