How to debug a Browser incompatiblity with a Web Site

This is a story about how I went about figuring out why a web site, one that I did not maintain, did not render in a specific web browser, and how to find a fix for this.

Not happy with a rendering bug

As a REAL Studio user, it bothered me for quite a while that their own integrated web browser was not capable of rendering the pages of REAL Software's own web site correctly. As this was their documentation (language reference) site, it was especially annoying, because it made looking up their documentation unnessarily cumbersome.

After a short inquiry why this isn't getting fixed, I got the response that this was because of a bug that's the responsibility of Apple, related to their Carbon version of their WebKit - case closed.

I was rather unhappy with this response. I could not understand why they couldn't do anything about it: It was their web server, i.e. they controlled the html pages that got rendered, and it was their browser, i.e. their code that loaded them. Granted, they were mainly using Apple's Webkit framework, which did the bad rendering, but still, it was under their control.

So I went ahead and tried to debug their thing, because they had given up on it, apparently.

Setting up my own test environment

Since their web site did render just fine under most other browsers, including their own browser when running on Windows, I needed to focus on the Apple Webkit browser side.

My own browser mimicking theirs

First, I created a very tiny webkit based browser with Xcode: Start a new Xcode project, which gave me already a blank window for a start, insert a "WebView" into the window's main view, and wrote a single line, found in Apple's Webkit docs, to load a webpage from a URL address.

That way, I could see that their web site also rendered wrong within my tiny browser. As this browser was using the Cocoa framework, not the alternative (and slowly being deprecated) Carbon version, I could already see that their the explanation they gave was wrong: They claimed it was Carbon related, but I found it was a general WebKit problem. Looks like they interpreted the results wrong, and gave up too early.

Now, it was pretty likely that something in the html or css code of their site was causing the problem. After all, even the tiny webkit browser I created could display similar pages, e.g. Wikipedia, correctly. I used Wikipedia as a comparison because their site was based on the same engine, i.e. Mediawiki.

Copying their web data to my own web server

Next, I needed to see if I could tweak their site's html or css code to make it work correctly with my test browser. Therefore, I had to copy an instance of their web page to another web server where I could then modify the html/css files. I decided to copy them to my OS X's own "personal webserver", which is running Apache and can be easily enabled via the System Preferences. The html file and others would go into /Library/WebServer/Documents.

When I first tried to manually copy the main html file and a few other the css files to my local web server directory, and then had my tiny browser to load that page, I found that the rendering problem was gone. This made it likely that one of the still missing files, i.e. those I had not transferred to my own webserver, was causing the trouble.

To verify this, I needed to get all involved files onto my own server. Luckily, Firefox helped me there: I loaded the original page from the RS site, and then used "Save As" with the option "Web page, complete" to save all files to my local web server directory.

Once I had my tiny browser load that completely copied page, I saw the bad rendering again. I.e, I could reproduce the error with my own browser and my own copy of the involved data.

Finding the problem once I had everything under control

The rest was easy: I removed individual files from the local web directory and kept reloading the page. At one point the rendering error would disappear - so I found the file that was causing the trouble. Then, since it was an original Mediawiki file, I looked for the same file on a Mediawiki website which rendered fine - i.e. on Wikipedia. I replaced the bad file with the one from Wikipedia, and voilą - problem solved!

This search took me, with some trial and error and with following one or two wrong paths, about 3 hours.

What they could have done

Had I been the maintainer of that site I could have done it in much less time, because much of my time was spent on trying to simulate their environment, before I could actually start doing the last step which quickly led me to the culprit. The first thing they should have done is to verify if that problem also occurs with a vanilla setup of the Wikimedia system they are using. That would quickly show whether it was their customization that caused the problem. In this case, it would have shown that, indeed, it wasn't their fault, as that Wikimedia version had the problem already built in. Next would be the standard response any support person on the phone would give: Have you installed all the latest updates? In that regard, checking with Wikipedia, which is a well maintained site based on the same framework, would have shown that it was not occuring there, thus probably gotten fixed. Next step would be to update the framework, which would have fixed this issue automagically.

Conclusion

As you can see, once I had my own "copy" of their setup I could easily modify it to the point where I spotted the cause. I do not know why the problem was originally not investigated enough to get to this point, but I wish that instead of telling us outsiders that it was a problem out of their and our reach, they had better given us some more information that would have encouraged others to look into this. After all, it was easy to fix once someone had the right idea where to look.

So what's the lesson here? If you get stuck, even if you don't have the time or nerve or desire to look into a problem, keep an open mind to it, and make it possible to allow others to take over. Admit that you couldn't do it for whatever reason, instead of making a statement that would cut off any further investigation, even by those who are willing. If someone else solves the puzzle, the joy of it will be shared by everyone, and no blame remains.