WebObjects Adaptor Test Plan

Before you develop your own WebObjects applications, you might want to use this test plan to be WebObjects is working properly.

The following test plan uses the HelloWorld and CyberWind example programs supplied with WebObjects. You'll use different URLs to access these applications with respect to the contents of the WebObjects.conf configuration file. You can check the WebObjects Adaptor's behavior by inspecting the CGIMessenger.log file to see if things are working as they should.

The WebObjects Adaptor attempts to contact a requested WebObjects application by following four steps:

  1. Choosing an application from the information in the URL and the WebObjects.conf configuration file.

  2. Load Balancing with an unresolved URL using the WebObjects.conf configuration file.

  3. Choosing an application from the private configuration file (/tmp/WebObjects.conf).

  4. Autostarting an application listed in the private configuration file.

If the WebObjects Adaptor fails to perform the first step, it jumps to the next.

This test plan tests the four main features of the WebObjects Adaptor. All tests should succeed unless stated otherwise. Perform the four tests in order, as each depends on the success of the previous test.


Setting up for testing

Be sure to have the WebObjects example programs HelloWorld and CyberWind in your Web server's DocumentRoot directory and start them up.

In a browser on a computer that does not host the Web server, type an URL to access one of these WebObjects applications.

On the Web server host, login as root and create a dummy logWebObjects file in the /tmp directory. This file will trigger the WebObjects Adaptor to log information about its behavior.

For example, from Terminal.app's command window issue the following commands

   your_host>  cd /tmp
   your_host>  touch logWebObjects
   your_host>  tail -f CGIMessenger.log 

The -f option for the tail command will generate continual updates to screen as the log file changes. You should read and understand the log information before marking a test as passed.

Use the ps command to verify that programs are running.

Now you should be ready for the first test.


Responding to a fully resolved URL

A URL that completely describes an application (fully resolved) looks like
   http://<host>/cgi-bin/WebObjects/CyberWind:1@<host> 
or
   http://<host>/cgi-bin/WebObjects/CyberWind:1 

The WebObjects Adaptor first assumes the application is on the computer hosting the Web server. When the adaptor receives such an URL, it looks in the /cgi-bin/WebObjects.conf file to find a port corresponding to this application. If the Adaptor finds one, it tries to connect to the application. If the Adaptor does not find a port number, it fails and returns an error message.


Testing a fully resolved URL

This first set of instructions shows you how to test the way the WebObjects Adaptor responds to URL requests for a WebObjects application.

  1. From a command window start four applications

  2. Create a /cgi-bin/WebObjects.conf file with the following contents (try different ordering)

  3. Try to contact the applications by issuing URLs from a browser on a remote computer.

This should work with no error messages. If so, go on to the second test.


Load Balancing with an unresolved URL

The WebObjects Adaptor responds to an unresolved URL by randomly picking a WebObjects application from the WebObjects.conf file. This random selection tends to distribute activity evenly across WebObjects application hosts.

An unresolved application URL looks like

   http://<host>/cgi-bin/WebObjects/CyberWind

When the adaptor receives such an URL, it reads the /cgi-bin/WebObjects.conf file to look for any application available under the name CyberWind and picks one randomly. Then the Adaptor completes the URL into a form such as

   http://<host>/cgi-bin/WebObjects/CyberWind:1@<host> 

As the user successively clicks on links, the same application should always be called back. There should be no more unresolved links in the page. All links in the page should look like

   http://<host>/cgi-bin/WebObjects/CyberWind:1@<host> 

rather than

   http://<host>/cgi-bin/WebObjects/CyberWind 


Testing load balancing with an unresolved URL

This second sequence tests the WebObjects Adaptor's response to unresolved URLs, with two additional WebObjects applications running.

  1. Add two more WebObjects applications on the Web server host, while the same four applications stay running.

  2. Complete the /cgi-bin/WebObjects.conf file by adding two new entries

  3. Restart the browser on the remote computer and try to make contact with the application

  4. Type several reloads from the browser at this stage and check the CGIMessenger.log to see that a different CyberWind application is picked each time.

  5. Go back through the application pages to the board page. Verify that your state is preserved (that is, if you select something in the board page, then go to another page and come back, your selection is still there.

  6. Now kill the two last processes.

  7. Try again requesting for

    This should fail two times out of six, as two of the six CyberWind applications listed in the configuration file are not running any more.

Now go on to the third test.


Choosing an application from the temporary configuration file

The WebObjects Adaptor may receive an unresolved URL for an application such as
   http:///cgi-bin/WebObjects/HelloWorld

The WebObjects Adaptor first parses the /cgi-bin/WebObjects.conf file.

There are cases when WebObjects Adaptor fails to find or open the /cgi-bin/WebObjects.conf file, or when the application is not listed in the /cgi-bin/WebObjects.conf file. In these cases, the WebObjects Adaptor proceeds by opening the /tmp/WebObjects.conf file, which is a non-public file, and should not be touched by the user.

In the /tmp/WebObjects.conf file you can only have one instance of a given application. If the adaptor finds the application it is looking for there, it will get its port number and connect to it.

When the developer starts an application (for example in gdb) without a -n argument, the port information will automatically be saved in the /tmp/WebObjects.conf file. There is no need to list the app in the /cgi-bin/WebObjects.conf file, as it will be considered unique on the computer hosting the Web server and has no application number.


Testing application choice from the temporary configuration file

To begin this third test, restart your browser on the remote computer. On the computer hosting the Web server, kill the HelloWorld processes and remove them from the /cgi-bin/WebObjects.conf file. Make sure you still have the four CyberWind processes (use the ps command to check).

  1. Start up HelloWorld

  2. Try to connect to HelloWorld from the browser.

    This should load-balance, based on the entries in the /cgi-bin/WebObjects.conf file.

  3. Type several reloads from the browser and observe in the CGIMessenger.log window that a different CyberWind application is picked each time. Then go through the application pages and go back to the board page. Verify that your state is preserved (that is, if you select something in the board page go to another page and come back, your selection is still there.

    This should use the /tmp/WebObjects.conf file. Try reloading to check that load-balancing doesn't work; you should always come back to the same application.

  4. Now kill the HelloWorld process and start it up again

    This should fail because port 4000 is already claimed by CyberWind:1.

  5. Try an unclaimed port number.

    From the browser try to contact CyberWind.

    This should load-balance using the /cgi-bin/WebObjects.conf file.

  6. Reload from the browser, check the CGIMessenger.log window for a different CyberWind application picked each time, then return the board page to verify that state is preserved.

    This should use the /tmp/WebObjects.conf file. Try reloading to check that load-balancing doesn't work; you should always come back to the same application.

  7. Now kill all CyberWind processes and remove them from the /cgi-bin/WebObjects.conf file.

  8. On the computer hosting the Web server start up CyberWind.

    From the browser try to connect to HelloWorld.

    This should use the /tmp/WebObjects.conf file. Try reloading to check that load-balancing doesn't work; you should not always come back to the same application.

  9. Now try

    This should use the /tmp/WebObjects.conf file. Try reloading to check that load-balancing doesn't work; you should not always come back to the same application.

Before you go on to the fourth and final test suite, kill the CyberWind and HelloWorld processes started in this section.


Autostarting from the temporary configuration file

In addition to the cgi-bin/WebObjects.conf file, the WebObjects Adaptor maintains a shadow version in the /tmp directory. This /tmp/WebObjects.conf file is created and maintained by the WebObjects Adaptor, so be careful not to alter this file in any way. The following example illustrates its use.

The WebObjects Adaptor may receive an application request with an unresolved URL such as

   http:///cgi-bin/WebObjects/CyberWind

The Adaptor first parses the /cgi-bin/WebObjects.conf file. If the Adaptor fails to find a match, it tries to parse the /tmp/WebObjects.conf file. There are cases when the WebObjects Adaptor fails. There may be no valid /tmp/WebObjects.conf file, or the application may not be listed in the /tmp/WebObjects.conf file, or the application listed in the /tmp/WebObjects.conf file may be a dead process. In these cases, the WebObjects Adaptor then tries to autostart the application CyberWind on the computer hosting the Web server.


Testing autostarting from the temporary configuration file

To test autostarting, restart your browser.

  1. On the computer hosting the Web server, kill the HelloWorld processes and remove them from the /cgi-bin/WebObjects.conf file. Make sure you still have the four CyberWind processes.

  2. From the browser try to connect to CyberWind.

    This should load-balance using the /cgi-bin/WebObjects.conf file.

  3. Reload from the browser, check the CGIMessenger.log to see that a different CyberWind application picked each time, then return the board page to verify that state is preserved.

  4. Try to connect to HelloWorld.

    This should autostart HelloWorld and use the /tmp/WebObjects.conf file. Try reloading to check that load-balancing doesn't work; you should not always come back to the same application.

  5. Now kill all CyberWind processes and remove them from the /cgi-bin/WebObjects.conf file.

  6. From the browser try to connect to HelloWorld.

    This should autostart HelloWorld using the /tmp/WebObjects.conf file. Try reloading to check that load-balancing doesn't work; you should not always come back to the same application.

  7. Now try to connect to CyberWind.

    This should autostart CyberWind using the /tmp/WebObjects.conf file. Try reloading to check that load-balancing doesn't work; you shouldn't always come back to the same application).

  8. Now try to contact a non-existent application.

    This should fail.

This completes the basic test plan for the WebObjects Adaptor. Of course, you could explore a little further.


Extra Points

Install each WebObjects application on a different host, then repeat these tests.

Try this test plan for each different platform (Windows NT, Solaris, and NEXTSTEP) running WebObjects. (Remember that a Web server on Windows NT cannot access WebObjects applications on UNIX hosts.)

Repeat tests on each platform (Windows NT, Solaris, NEXTSTEP) not running WebObjects.

Repeat also on Windows NT and Solaris by using WebObjects Netscape Interface (NSAPI) Adaptor instead of the standard CGI WebObjects Adaptor. The syntax of the URLs stays the same.