FFClickOnce Testing Manual

A Guide for Mozilla Update editors

Author:	James Dobson
Contact:	dobson@softwarepunk.com
Date:	2007-04-10 (Documentation last updated)
Version:	0.6 (FFClickOnce version to which this document applies)

Introduction

This document is intended for the extension reviewers at the Mozilla Update site, so that they can quickly audit the functionality of my FFClickOnce extension. Version 0.2 of my extension did not pass review [1] because the reviewer did not have enough information about what ClickOnce is, what FFClickOnce does, and how to test that it does what it's supposed to do. Additionally, it is my hope that this document can serve as an illustration to users of what FFClickOnce does and how to configure it.

To assist in testing, I have created a simple application that is deployed via the ClickOnce technology. The application is run from the ClickOnce Tester download page.

Prerequisites

There are several things that you must installed before you can test the FFClickOnce extension. First, you need to have a compatible version of Firefox. I have tested with Firefox 1.5 and Firefox 2.0.0.1.

Second, you need to have an operating system that supports Microsoft .NET version 2.0. Currently, these operating systems are [2]: Windows 2000 Service Pack 3; Windows 98; Windows 98 Second Edition; Windows ME; Windows Server 2003; Windows Vista Business; Windows Vista Business 64-bit edition; Windows Vista Enterprise; Windows Vista Enterprise 64-bit edition; Windows Vista Home Basic; Windows Vista Home Basic 64-bit edition; Windows Vista Home Premium; Windows Vista Home Premium 64-bit edition; Windows Vista Starter; Windows Vista Ultimate; Windows Vista Ultimate 64-bit edition; and Windows XP Service Pack 2.

Third, you need to have Microsoft .NET Framework version 2.0 installed on your system. If you don't already have it, you may download it from the .NET Framework 2.0 download page. (Updates to this framework, as well as the .NET SDK download, can be found at the .NET Downloads Page.) The .NET Framework is a fairly large, > 20 MB download.

Fourth and finally, you need to install FFClickOnce itself. This document assumes you have installed FFClickOnce version 0.6.

Out-of-the-Box Functionality Test

Begin by going to the ClickOnce Tester download page. This page will help you run a small application, called ClickOnce Tester, that you can use to verify that ClickOnce is working correctly on your system. You should see the following web page:

The application download page, .NET 2.0 successfully detected.

If you see something other than this page, then it is an error. If this page tells you that a prerequisite (.NET Framework 2.0) is required, then it means that FFClickOnce has failed to properly detect the presence of .NET 2.0 on your computer. Please email me for help troubleshooting this problem.

Assuming you see the correct web page, then everything is fine. Proceed by clicking the "Run" link. After a moment, the Firefox download confirmation window should appear. Depending on your version of Firefox, one of the windows below should appear:

The dialog that appears in Firefox versions 2.0 and earlier

The dialog that appears in Firefox versions 2.0.0.1 and later.

In Firefox version 2.0 and earlier, select the radio button option that says "Run ClickOnce Application" and press "OK". In Firefox version 2.0.0.1 and later, click the "Run ClickOnce Application" button.

If this window is missing the "Run ClickOnce Application" option, then it means that the web server's MIME type associations are not properly configured. The webserver hosting the ClickOnce application must be configured to associate ".application" files with the MIME type "application/x-ms-application".

After you press "OK", control is transferred to your local machine, which will launch the ClickOnce application. While it is launching, you will probably see the following window:

The standard window that appears as a ClickOnce application is loading.

Once you see this window, you know that FFClickOnce has done its job successfully. Anything that happens after this window appears is out of my control as the author of FFClickOnce. If this is the first time that you have downloaded a particular ClickOnce application, you will probably see a download progress window. You may also be asked whether or not you trust the ClickOnce application. The ClickOnce Tester application that I have provided requests a minimal set of privileges, and therefore will likely not require your approval before it can execute.

Note

Some firewall software will prevent ClickOnce applications from downloading. If the download of your ClickOnce application never progresses past 0%, it is likely that this is happening. Please reconfigure your firewall to allow ClickOnce to contact the internet. I believe the application name that you will have to tell your firewall software is "dfsvc.exe".

If the ClickOnce process works correctly, you'll see the ClickOnce Tester application on your screen:

The ClickOnce Tester application.

If you got this far without any problems, it means that the default settings for FFClickOnce are working correctly. Please continue to the next section.

Immediate Run Option Test

When you click on a ClickOnce link, it brings up Firefox's download confirmation window, in which you have to choose the "Run ClickOnce Application" radio button and then press "OK". Internet Explorer, on the other hand, doesn't have this intermediate stage; it runs the application immediately. Several people suggested that FFClickOnce should have this capability, too. While there are good reasons [3] to keep it the way it always was, I have added this capability to FFClickOnce nonetheless, to make the experience of using a ClickOnce application from Firefox as seamless as using one from Internet Explorer.

To configure this "Immediate Run" capability, select "Extensions"[4] from the "Tools" menu of Firefox. You should see the Extensions window:

The Firefox Extensions window.

Select the FFClickOnce extension from this window, and then click on the "Options" button. The FFClickOnce options window should appear:

The FFClickOnce options window.

To enable the "Immediate Run" cability, please ensure the checkbox called "Don't prompt before running application" is checked and press "OK". Now close the Firefox Extensions window.

Now, go to the ClickOnce Tester download page in your browser once again, and click on the "Run" link. This time, you should not see the Firefox download confirmation window. Instead, FFClickOnce should immediately transfer control to ClickOnce, and the application should launch. You may see the standard launching window while waiting for the application to launch:

The standard window that appears as a ClickOnce application is loading.

If everything worked as expected, it means that the "Immediate Run" option for FFClickOnce is working correctly. Please continue to the next section of this document.

Discontinue Reporting of Installed .NET Framework Versions

By default, FFClickOnce is configured to scan for .NET Frameworks that have been installed on your computer and to report this information to webservers. This enables a ClickOnce application's download page to display the appropriate information to you. Unfortunately, this "leaks" a bit of information about your computer to every website you visit.

Specifically, the information that is leaked is the version number of the latest release of the .NET Framework that is installed on your computer. Some really paranoid people might not want this information available to everyone on the web, so the FFClickOnce options window provides a way to turn this feature off. The tradeoff; however, is that a ClickOnce application's download page won't be able to detect whether or not you have the prerequisite (.NET Framework 2.0) for running a ClickOnce application.

To discontinue reporting of the .NET Framework versions, select "Extensions"[4] from the "Tools" menu of Firefox. You should see the Extensions window:

The Firefox Extensions window.

Select the FFClickOnce extension from this window, and then click on the "Options" button. The FFClickOnce options window should appear:

The FFClickOnce options window.

Now remove the check mark from the checkbox called "Report .NET Framework version to web servers" and press "OK". Now close the Firefox Extensions window.

Go to the ClickOnce Tester download page in your browser once again. Notice that the page is slightly different this time:

The application download page, .NET 2.0 not detected.

This page is different than the original page. It tells the user that a prerequisite is possibly missing, and provides two links for the user to click:

The "Run" link at the bottom of the page is actually a link to a file called "setup.exe". This program will check the machine for the prerequisites, download them if they are missing, and then run the ClickOnce application. If they are not missing, it will just run the ClickOnce application immediately.

The "launch" link in the middle of the text is a link directly to the ClickOnce application.

Click on the "launch" link and verify that the ClickOnce application loads correctly.

If you have reached this point in the document, you can be confident that FFClickOnce will allow you to use ClickOnce applications on your computer from the Firefox browser. Also, you have been introduced to all of the features of FFClickOnce pertaining to ClickOnce applications. If you are reading this document as a user guide, you may stop here.

The rest of this document contains information about additional tests that should be performed on FFClickOnce, probably only by the developers of FFClickOnce. If a version of FFClickOnce is being tested before being publically released, then the tester should also conduct these additional tests.

Firefox Plugin Compatibility

The plugin architecture of Firefox seems to have difficulties processing user agent strings longer than 127 characters in length. This means that, with the "Report .NET Framework version to web servers" feature enabled, FFClickOnce can potentially generate a user agent string that causes the browser to crash when loading certain plugins, most notably the Java plugin.

As of my latest testing, Firefox 1.5.0.4 crashes completely due to this bug. Firefox 2.0.0.1 also crashes.

As of version 0.4 of the FFClickOnce extension, code has been added to prevent this from happening. However, it is important to test that this code is functioning correctly, so this section will show how to do this. None of these tests should cause the browser to crash.

Turn Reporting Back On

First, reporting of .NET Framework versions must be enabled. Select "Extensions"[4] from the "Tools" menu of Firefox. You should see the Extensions window:

The Firefox Extensions window.

Select the FFClickOnce extension from this window, and then click on the "Options" button. The FFClickOnce options window should appear:

The FFClickOnce options window.

Now ensure that the checkbox called "Report .NET Framework version to web servers" is checked, and press "OK". Now close the Firefox Extensions window.

Run a Java Applet

This step doesn't actually test any specific functionality of FFClickOnce, and may be skipped if desired. It is included in this document only as a step for the developers of FFClickOnce to follow, just to ensure that the compatibility bug with Java will not happen again. A failure in this step does not necessarily indicate a problem with FFClickOnce. A success in this step does not necessarily indicate that FFClickOnce is working correctly (there may be no overflow of the user agent string).

To conduct this test, the URL of a page that loads some Java applets is necessary. Doing a quick Google search, I found the following link that may be used if desired: http://www.w3.org/People/mimasa/test/object/java/clock

With reporting of .NET Framework versions enabled, as done in the previous step, just visit the URL with the Java applets. If the Java applets execute and there is no crash of the browser, then no further examination is warranted.

If this test fails, then the test should be re-done, but with .NET Framework version reporting disabled. If that doesn't fail, then there may be a problem in FFClickOnce.

Test User Agent Overflow Notification

In this step, we artificially increase the length of the browser's user agent to provoke FFClickOnce, causing it to shut off reporting of .NET Framework versions and to notify the user of a potential problem. We assume that .NET Framework reporting is switched on at the beginning of this test. If it is not, please see the section Turn Reporting Back On above.

First, navigate to the about:config URL and right click anywhere on the list of preferences, first choosing "New" and then "String" from the context menu that appears.

When prompted for the name of the preference, please use "general.useragent.extra.ffcotest", [5] without the quotation marks. At the next prompt, you must enter the value of the preference. Please use the value "A123456789B123456789C123456789D123456789E123456789", again without the quotation marks.

Now we must verify that the preference has been added. Enter "general.useragent" in the "Filter" field near the top of the about:config page, and press the Enter key. The following figure shows approximately what the preferences page should look like:

The Firefox preferences page, with an erroneous extension to the user agent.

Now, exit your browser and restart it. Before the browser loads, you should see the following warning dialog box:

A dialog box warning the user that the user agent string has exceeded a safe length.

To verify that reporting is actually switched off, go to the ClickOnce Tester download page in your browser once again. Notice that the page is of the format when the .NET framework reporting is switched off:

The application download page, .NET 2.0 not detected, because .NET Framework reporting is switched off.

Finally, it should be verified that the FFClickOnce extension will not allow the user to turn reporting back on again. Select "Extensions"[4] from the "Tools" menu of Firefox. You should see the Extensions window:

The Firefox Extensions window.

Select the FFClickOnce extension from this window, and then click on the "Options" button. The FFClickOnce options window should appear:

The FFClickOnce options window.

The checkbox called "Report .NET Framework version to web servers" is currently not checked. Try clicking on it. The warning dialog box that you saw when you restarted the browser should appear. When you click on "OK" in the dialog box, you should see that the checkbox that you clicked on remains unchecked.

Now, clean up what has been done to Firefox. Go to the about:config page and find the "general.useragent.extra.ffcotest" preference. Right click on it, and choose "Reset" from the context menu. In the FFClickOnce options window, re-enable "Report .NET Framework version to web servers". Now that the user agent string is shorter again, FFClickOnce should allow reporting to work once again.

Conclusion

Assuming you have reached this point in the document without having any difficulties, it means that the FFClickOnce extension is working correctly on your computer.

[1]

Version 0.2 didn't pass review, even though it was exactly the same as version 0.1, except that the version number in the install.rdf file had been bumped so that Firefox 2.0a1 would accept the extension. Version 0.1 reviewed successfully because the reviewer contacted me so that I could provide him with a URL to a sample ClickOnce application so that he could test it.

[2]

I took this list from the .NET Framework 2.0 download page. It may change over time as new version of the .NET Framework are releases, but I will try to keep it synchronized with Microsoft's list. Also note that, while the Mono Project provides a fairly complete implementation of the .NET 2.0 specification for a variety of non-Microsoft platforms, it does not currently have an implementation of the ClickOnce technology.

[3]

There are a couple reasons why it is a good idea not to run the ClickOnce application immediately. One reason is that it gives people a chance to actually download the ClickOnce ".application" file, rather than always running it.

The main reason; however, is that it is more secure because it gives the user a chance to back out of running a ClickOnce application. A ClickOnce link can appear anywhere--it doesn't have to appear on a standard, Microsoft-looking page. Also, a ClickOnce link doesn't have to end in the extension ".application"; depending on the configuration of the web server, a link to ClickOnce application could even end in something really stupid, like ".txt"! This means that it is impossible to know if the link you are clicking on will suddenly decide to download and run a ClickOnce application.

Thankfully, ClickOnce applications have to request security permissions to do anything particularly nasty to your system. Yet this is not foolproof. A poor security configuration or (god forbid) a bug in the .NET Framework could allow an application to do more than it should. Or perhaps an application might just spoof a window of a legitimate program on your computer, to nefarious ends. My belief is that it is best for a user to know when they are using code that has come from a network source, no matter how "trusted" that source may be.

[4]	(1, 2, 3, 4) In Firefox 2.0, please choose "Add-ons" from the "Tools" menu to get the list of extensions. Also, the "Options" button appears not at the bottom of the Extensions window, but near an extension when that extension is selected.

[5]	This setting is not a special feature of FFClickOnce; rather, Firefox automatically appends the value of any configuration settings that begin with "general.useragent.extra." to the User Agent string.