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 will 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 APICalls.html. 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.

• Please read all you can about the following topics:
  • XPCOM
  • XPConnect
  • RDF
  • JavaScript
  • XUL
  • HTML
  • Mozilla Mail 5.0 Architecture
  
  
• Check the APICalls.html file to see which interfaces require testcases.
• Actually use the Messenger 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 5.0 is shipped.

1. Go to APICalls.html 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 Prog 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 ProgID 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 ProgID 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 form that includes buttons for all the methods or variables that will be tested
      5. A series of functions that start with Do_XXX that will test the method or variable
   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 ProgID 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. Set up the form and associated functions
      1. Go to the form and change the button values to reflect the methods to be tested.
      2. Create a series of empty fuctions named Do_XXXX with XXXX replaced by the name of the method to be tested
      3. Associate a link between the each button and its function
         1. Example:
            is mapped to a function Do_SetTo()
   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 a testcase in APICalls.html, you will be provide the filename you should use.
      1. var sFilename = "mncompose004.html"
   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. 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.
   10. If at any time during the running of a function, the expected result fails then change the global variable result to fail

• 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

• \mozilla\mailnews\addrbook
  • \build\nsAbBaseCID.h
  • \build\nsAbFactory.cpp
  • \public\nsIAbAddressCollector.idl
  • \public\nsIAbBase.idl
  • \public\nsIAbCard.idl
  • \public\nsIAbDirectory.idl
  • \public\nsIAbListener.idl
  • \public\nsIAddrBookSession.idl
  • \public\nsIAddrDatabase.idl
  • \public\nsIAddrDBAnnouncer.idl
  • \public\nsIAddrDBListner.idl
  • \public\nsIAddressBook.idl
  • \public\nsIAutoCompleteListener.idl
  • \public\nsIAutoCompleteSession.idl
• \mozilla\mailnews\base
  • \build\nsMsgBaseCID.h
  • \build\nsMsgFactory.cpp
  • \public\nsICopyMessageListener.idl
  • \public\nsICopyMsgStreamListener.idl
  • \public\nsIFolder.idl
  • \public\nsIFolderListener.idl
  • \public\nsIMessage.idl
  • \public\nsIMessageView.idl
  • \public\nsIMesseneger.idl
  • \public\nsIMsgAccount.idl
  • \public\nsIMsgAccountManager.idl
  • \public\nsIMsgBiffManager.idl
  • \public\nsICopyServices.idl
  • \public\nsICopyServiceListener.idl
  • \public\nsIMsgFolder.idl
  • \public\nsIMsgFolderCache.idl
  • \public\nsIMsgFolderCacheElement.idl
  • \public\nsIMsgGroupRecord.idl
  • \public\nsIMsgHdr.idl
  • \public\nsIMsgHost.idl
  • \public\nsIMsgIdentity.idl
  • \public\nsIMsgIncomingServer.idl
  • \public\nsIMsgMailNewsUrl.idl
  • \public\nsIMsgMailSession.idl
  • \public\nsIMsgMessageService.idl
  • \public\nsIMsgSignature.idl
  • \public\nsIMsgStatusFeedback.idl
  • \public\nsIMsgMsgThread.idl
  • \public\nsIMsgVCard.idl
  • \public\nsIMsgWindowData.idl
  • \public\nsIUrlListener.idl
  • \public\nsIUrlListenerManager.idl
  • \public\nsMsgFolderFlags.idl
• \mozilla\mailnews\compose
  • \build\nsIMsgCompCID.h
  • \build\nsIMsgCompFcatory.cpp
  • \public\nsIMsgCompFields.idl
  • \public\nsIMsgCompose.idl
  • \public\nsIMsgComposeService.idl
  • \public\nsIMsgDraft.idl
  • \public\nsIMsgQuote.idl
  • \public\nsIMsgSend.idl
  • \public\nsIMsgSendLater.idl
  • \public\nsIMsgSendLaterListener.idl
  • \public\nsIMsgSendListener.idl
  • \public\nsISmtpService.idl
• \mozilla\mailnews\db
  • \msgdb\build\nsMsgDBCID.h
  • \msgdb\build\nsMsgDBFactory.cpp
  • \msgdb\public\nsIDBChangeAnnouncer.idl
  • \msgdb\public\nsIDBChangeListener.idl
  • \msgdb\public\nsIDBFolderInfo.idl
  • \msgdb\public\nsIMsgDatabase.idl
• \mozilla\mailnews\idl
  • \MailNewsTypes.idl
• \mozilla\mailnews\imap
  • \build\nsIMsgImapCID.h
  • \build\nsImapFactory.cpp
  • No IDL files for imap at this time
• \mozilla\mailnews\local
  • \build\nsMsgLocalCID.h
  • \build\nsMsgLocalFactory.cpp
  • \public\nsIMailboxService.idl
  • \public\nsIMailboxUrl.idl
  • \public\nsIMsgParseMailMsgState.idl
  • \public\nsIPop3IncomingServer.idl
  • \public\nsIPop3Service.idl
  • \public\nsIPop3Sink.idl
  • \public\nsIPop3URL.idl
• \mozilla\mailnews\mime
  • \abstatus\build\nsMiscStatusFactory.cpp
  • \emitters\build\nsMimeEmitterCID.h
  • \emitters\build\nsEmitterfactory.cpp
  • \public\nsIMimeEmitter.idl
  • \public\nsIMimeMiscStatus.idl
  • \public\nsIMimeStreamConverter.idl
  • \public\nsIMimeURLUtils.idl
  • \public\nsIMsgHeaderParser.idl
• \mozilla\mailnews\movemail
• \mozilla\mailnews\news
  • \build\nsMsgNewsCID.h
  • \build\nsMsgNewsFactory.cpp
  • \public\nsIMsgOfflineNewsState.idl
  • \public\nsINNTPArticleList.idl
  • \public\nsINNTPCategory.idl
  • \public\nsINNTPCategoryContainer.idl
  • \public\nsINNTPHost.idl
  • \public\nsINntpIncomingServer.idl
  • \public\nsINNTPNewsgroup.idl
  • \public\nsINNTPNewsgroupList.idl
  • \public\nsINNTPNewsgroupPost.idl
  • \public\nsINntpService.idl
  • \public\nsINntpUrl.idl
• \mozilla\mailnews\public
  • MailNewsTypes2.idl
• \mozilla\mailnews\ui

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