Mozilla

• Roadmap
• Projects
• Coding
  • Module Owners
  • Hacking
  • Get the Source
  • Build It
• Testing
  • Releases
  • Nightly Builds
  • Report A Problem
• Tools
  • Bugzilla
  • Tinderbox
  • Bonsai
  • LXR
• FAQs

 

Introduction

This document describes the basics needed to start testing the Mail API. A working knowledge of JavaScript is assumed. We are looking for people to take ownership of an API interface and provide testcases for all the methods and properties that exist within that interface. We have a standard template that we follow for setting up the testcases and reporting the results. This template will hopefully be connected to a database in the future to keep track of testcase pass/fail history. In the meantime, we want people to develop testcases. If you participate, you will be assigned an interface and your name will be displayed in API Testcasesdatabase. It helps to know C++ as well since many times you need to look at the actual code of Mozilla to understand what the API call is trying to accomplish. You will get to know and understand Mozilla and its components better and will learn about some of the standards that Mozilla is implementing. If you are interested in participating, please email the coordinator Par Pandit.

Before you can start

• Please read all you can about the following topics:
  • XPCOM
  • XPConnect
  • RDF
  • JavaScript
  • XUL
  • HTML
  • Mozilla Mail 5.0 Architecture
  
  
• Check the API Testcases database to see which interfaces require testcases.
• Actually use the Mail email client before starting so you will have a better understanding of the features and functions calls.
• Finally understand that not everything is implemented nor is it guaranteed to be before Mozilla and Netscape 6 is shipped.

1. Go to Test Case Status database to find out which interfaces need testing and choose an interface. For our purposes we will chose the interface nsIMsgCompFields in the file /mozilla/mailnews/compose/public/nsIMsgCompFields.idl
2. Determine the Contract ID for the interface 
   1. Go to the component's public directory
      1. Example: cd \mozilla\mailnews\compose\public
   2. Open the component factory file
      1. Example: notepad \mozilla\mailnews\compose\build\nsMsgCompFactory.cpp
      2. In the NSRegisterSelf function look for the ContractID for MsgCompFields
         1. Notice the component://netscape/messengercompose/ composefields in
            rv = compMgr->RegisterComponent( kCMsgCompFieldsCID, "Message Compose Fields", "component://netscape/messengercompose/composefields", path, PR_TRUE, PR_TRUE);
            
         2. Copy the ContractID into a buffer or text page
3. Create a new testcase
   1. All the testcases contain the following the basic format
      1. Header to describe name and status
      2. Global variables contained within the HEAD section
      3. Some code that is included as part of the automation testing that we are planning to do
      4. A main() function that will be called from the Testcase() function
      5. Security code within any set of brackets ("{", "}" ) that will allow javascript to access the mail client
   2. Start a new testcase by copying from an existing testcase or the standard template
   3. In order to get an instance of the interface, use an existing one (getService) or create one (createInstance). Use getservice() if the interface is a singleton. Use createInstance() if the interface is not a singleton and if you want to create a new object. Modify the testcase code to use the ContractID you saved in the buffer. For the example we would use createInstance() but both methods are provided below.
      1. instanceofcompfields = Components.classes[ 'component://netscape/messengercompose/composefields']. createInstance();
      2. instanceofcompfields = Components.classes[ 'component://netscape/messengercompose/composefields']. getservice();
   4. Do a interface query to verify that you access the COM object as the interface you want to test
      1. instanceofcompfields. QueryInterface (Components.interfaces.nsIMsgCompFields);
   5. Add a switch statement that returns "Pass" if the result variable is true and 'Fail" if is is false.
   6. Change the dump and document.wrote statements to reflect the interface you are testing
   7. Change sFilename to reflect the name of the testcase. When you are assigned an interface, you will be provided the filename you should use. Check Test Case Status
      1. var sFilename = "mncompose004.html"< /li >
   8. Change the parameters of Testcase to reflect the name of the testcase and Interface

      1. aTestcases[tc++] = new Testcase(sFilename,
                                        "nsIMsgCompFields",
                                        "Pass",
                                        GetTheComposeSession(),
                                        "Bug report required");

   9. Added the following preference to your profile's prefs.js file: user_pref("signed.applets.codebase_principal_support", true);
   10. Now comes the hard part. Actually write the function calls and have the output go to the textarea of the form. This includes making sure you receive and handle the nsresult output from most function and do error handling.
   11. If at any time during the running of a function, the expected result fails then change the global variable result to fail

Possible Problems

You will encounter many possible problems when trying to test XPConnect. Here is a list of the current known ones.

• Anything within the C++ markings in IDL files is not testable such as the following from nsIMsgSend.idl

  • %{C++
    #include "nsIURL.h"
    #include "rosetta.h"
    #include "rosetta_mailnews.h"
    %}		

  • %{ C++
    enum
    {
      nsMsgDeliverNow = 0,
      nsMsgQueueForLater = 1,
      nsMsgSave = 2,
      nsMsgSaveAs = 3,
      nsMsgSaveAsDraft = 4,
      nsMsgSaveAsTemplate = 5
    } /* nsMsgDeliverMode */;
    %}		

  • %{ C++
    typedef nsresult (*nsMsgSendCompletionCallback)
            (nsresult aExitCode, 
    	void *tagData, 
    	nsFileSpec *returnFileSpec);
    typedef nsresult (*nsMsgSendUnsentMessagesCallback)
            (nsresult aExitCode, 
    	PRUint32 totalSentCount, 
    	PRUint32 totalSentSuccessfully, 
    	void *tagData);
    %}		

  • %{ C++
    // Attachment file/URL structures
    struct nsMsgAttachmentData
    {
      nsIURI  *url;	
      char *desired_type;	
      char *real_type;
      char *real_encoding;	
      char *real_name;
      char *description;			 
      char *x_mac_type, *x_mac_creator; 
    };		

• Anything with the word [native] is not testable
  • Example: [ptr] native sendListenerPtr(nsIMsgSendLaterListener *) in IMsgSendLater.idl
• Interfaces that contain [noscript] mean the following methods are not testable (???)
• There are several data structure which are not possible to construct within JavaScript
  • nsISupports: void AddUnique(in nsISupports element) in nsIAbBase.idl (???)
  • nsISupportsArray: void DeleteDirectories(in nsISupportsArray dierctories) in nsIAbDirectory
  • nsFileSpec: void OpenMDB(in nsFileSpec dbName, in boolean create) in nsIAddrDatabase.idl
  • nsIDOM*: void DeleteCards(in nsIDOMXULElement tree, in nsIDOMXULElement srcDir, in nsIDOMNodeList node) in nsIAddressBook
  • 
    
• Scriptable functions which contains parameters that have any of the possible problems above are not testable

Glossary

dump

send output to the DOS debug window when seamonkey is running

http

Hypertext Transfer Protocal is designed to be a small, fast protocal that is well suited for distributed multimedia information systems and hypertext jumps between sites

mime

MIME is a series of specifications that describe how to represent binary data as text so that they may be sent via text-based electronic mail.

native

This is the same (as far as xpconnect is concerned) as declaring it as a void*

singleton

A 'singleton' object is one in which the object can be created only once. There cannot be multiple instances of a singleton objects. Most of the services & sessions interfaces are singleton.

additional mozilla terms

http://www.mozilla.org/docs/jargon.html

---