embedding/qa/testembed/README.TXT

   1 ***** BEGIN LICENSE BLOCK *****
   2 Version: MPL 1.1/GPL 2.0/LGPL 2.1
   3
   4 The contents of this file are subject to the Mozilla Public License Version
   5 1.1 (the "License"); you may not use this file except in compliance with
   6 the License. You may obtain a copy of the License at
   7 http://www.mozilla.org/MPL/
   8
   9 Software distributed under the License is distributed on an "AS IS" basis,
  10 WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11 for the specific language governing rights and limitations under the
  12 License.
  13
  14 The Original Code is is mozilla.org code.
  15
  16 The Initial Developer of the Original Code is
  17 Netscape Communications Corporation.
  18 Portions created by the Initial Developer are Copyright (C) 1998
  19 the Initial Developer. All Rights Reserved.
  20
  21 Contributor(s):
  22   Chak Nanga <chak@netscape.com>
  23   David Epstein <depstein@netscape.com>
  24
  25 Alternatively, the contents of this file may be used under the terms of
  26 either the GNU General Public License Version 2 or later (the "GPL"), or
  27 the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28 in which case the provisions of the GPL or the LGPL are applicable instead
  29 of those above. If you wish to allow use of your version of this file only
  30 under the terms of either the GPL or the LGPL, and not to allow others to
  31 use your version of this file under the terms of the MPL, indicate your
  32 decision by deleting the provisions above and replace them with the notice
  33 and other provisions required by the GPL or the LGPL. If you do not delete
  34 the provisions above, a recipient may use your version of this file under
  35 the terms of any one of the MPL, the GPL or the LGPL.
  36
  37 ***** END LICENSE BLOCK *****
  38
  39 TestEmbed is a C++ test app based upon mfcEmbed. It includes
  40 individual test cases for Embedding interface methods. Interfaces
  41 covered include nsIFile & nsILocalFile, nsISHistory, nsIWebNavigation,
  42 nsIWebProgressListener, nsIClipboardCommands, nsIRequest, nsIDOMWindow,
  43 nsIDirectoryService, nsIProfile, nsIObserverService, nsIWebBrowser,
  44 nsIWebProgress, nsIWebBrowserFind, nsIEditingSession, nsICommandManager,
  45 nsICommandParams, nsIStreamListener, nsIURIContentListener,
  46 nsISHistoryListener, nsIWebBrowserChrome, and nsIEmbeddingSiteWindow.
  47 .
  48 Individual tests also exist for methods found in nsIGlobalHistory
  49 and nsIProfile.
  50
  51 In addition to the mfcEmbed menus, it contains 5 menus: Tests,
  52 Interfaces, Tools, Verified Bugs, and Clipboard Commands.
  53
  54 Executed test cases print output to a logfile called TestOutput.txt.
  55 This will be created in the C:\temp folder.
  56
  57 See build instructions below.
  58
  59 General Overview:
  60 -----------------
  61
  62 1. The TestEmbedApp creates BrowserFrames
  63
  64 2. BrowserFrame creates the toolbar, statusbar, URLbar
  65    BrowserView etc.
  66    BrowserFrames implement the IBrowserFrameGlue interface
  67    using which new BrowserFrames can be created, statusbar
  68    updated etc.
  69
  70 3. BrowserView creates the embeddable browser instance and
  71    manages user interaction such as URL navigation etc.
  72    BrowserView connects the BrowserImpl with the BrowserFrame
  73    via the IBrowserFrameGlue interface
  74
  75 4. BrowserImpl implements the set of required/optional Gecko
  76    embedding interfaces
  77
  78
  79 Start by first looking at TestEmbed.cpp
  80
  81 Files:
  82
  83 StdAfx.h
  84         - Includes the required Mozilla header files
  85
  86 TestEmbed.cpp
  87         - CWinApp derived class
  88         - Creates the browser's main frame window etc
  89           using the CreateNewBrowserFrame() and loads
  90           the HomePage
  91         - Makes the required NS_InitEmbedding() and the
  92           NS_TermEmbedding() calls in the app's InitInstance()
  93           and ExitInstance() functions
  94         - Keeps track of the list of new BrowserFrames created
  95           which it cleans up properly in ExitInstance()
  96
  97 BrowserFrm.cpp
  98         - This is the browser's Frame window i.e. the one with the
  99           "chrome" - with the toolbar, urlbar etc.
 100         - Creates the toolbar, URLbar, statusbar, progressbar
 101           also the browser's view window.
 102
 103 BrowserFrameGlue.cpp
 104         - Implements the IBrowserFrameGlue interface. This interface
 105           contains platform specific implementations of functions to
 106           update the statusbar, creating new browser frames etc. Embedded
 107           browser's callbacks use this interface when needed
 108
 109 BrowserView.cpp
 110         - Creates the embedded browser object and handles most aspects
 111         of the embedded browser interactions - like URL navigation,
 112         clipboard interactions etc
 113         - Also has code to keep the menu/toolbar/statusbar UI items up
 114         to date
 115         - It's the view which conntects the BrowserFrame to the BrowserImpl
 116           (see below) by passing it the pointer to IBrowserFrameGlue
 117
 118 BrowserImpl*.cpp
 119         - Implements the required and/or optional embedded browser
 120         interfaces
 121         (BrowserImpl.cpp implements the set of interfaces which
 122         are required by Gecko of all embedding apps. The other
 123         interfaces implemented in the BrowserImpl*.cpp files are
 124         optional. Included in the BrowserImpl.cpp file are interface tests for                                  nsIWebBrowserChrome,nsIEmbeddingSiteWindow, nsIStreamListener, and                              nsIURIContentListener.)
 125
 126         - Calls on the statusbar/progressbar update functions exposed
 127         via the IBrowserFrameGlue in response to the nsIWebProgressListener
 128         interface callbacks. nsIWebProgressListener methods are implemented
 129         in BrowserImplWebPrgrsLstnr.cpp. nsISHistoryListener methods are
 130         implemented in BrowserImplHistoryLstnr.cpp
 131
 132 Dialogs.cpp
 133         - Contains dialog box code for displaying Prompts, getting
 134         passwords, getting username/passwords etc
 135         - Contains the CFindDialog class - used for searching text
 136         in a web page
 137
 138 winEmbedFileLocProvider.cpp, ProfilesDlg.cpp, ProfileMgr.cpp
 139         - Profile management related code (by Conrad Carlen)
 140
 141 Tests.cpp
 142         - This is where individual test cases are stored and test interfaces are
 143         registered. The file is divided into three sections: 1) individual test
 144         cases corresponding to the "Tests" menu. 2) tools that are helpful,
 145         corresponding to the "Tools" menu. These include routines like
 146         removing all entries from Global History. 3) Registration of
 147         interface tests with CTests object (bottom part of the file). Example:
 148
 149         void CTests::OnInterfacesNsidomwindow()
 150         {
 151                 CDomWindow oDomWindow(qaWebBrowser) ;
 152                 oDomWindow.OnStartTests(nCommandID);
 153         }
 154
 155         The interface tests OnInterfacesNsidomwindow() is associated with menu
 156         handlers in the message map (in top part of the file). For this example,
 157         ON_COMMAND(ID_INTERFACES_NSIDOMWINDOW_RUNALLTESTS, OnInterfacesNsidomwindow).
 158         The test interface object (oDomWindow) is created with appropriate constructor.
 159         Then the object calls the test interface's OnStartTests() method and passes
 160         the selected command ID.
 161
 162
 163 QAUtils.cpp
 164         - This contains routines that are useful to QA. Such tasks as
 165         printing to a logfile, displaying messages to the screen, formatting
 166         output data, retrieving the name of an nsI request, and getting a urI
 167         are stored here.
 168
 169 makefile.in
 170         - We define "_AFXDLL" and for the compiler and specify
 171         "-SUBSYSTEM:windows" for the linker using LCFLAGS and
 172         LLFLAGS, respectively
 173         - We also define "USE_SINGLE_SIGN_ON" to enable the
 174         single sign-on support
 175         - Also need REQUIRES for all modules to be included
 176         - Place all .cpp files for compiling in CPPSRCS section.
 177
 178 testembed.dsp and testembed.dsw
 179         - These VisualStudio workspace/project files can be used
 180         to open/build this sample inside of the VC++ IDE
 181
 182 Most interface tests have their own .cpp & .h files (e.g. nsIWebBrow.cpp).
 183
 184 Instructions for building:
 185         1) Open a dos shell.
 186         2) cd /mozilla/embedding/qa/testembed      // testEmbed directory
 187         3) Copy the makefile.in file and call it makefile. Place in same directory.
 188         4) Change the top few lines in 'makefile' to indicate local pathway. Example:
 189                 DEPTH           = ../../..
 190                 topsrcdir       = d:/mozilla_src/mozilla
 191                 srcdir          = d:/mozilla_src/mozilla/embedding/qa/testembed
 192                 VPATH           = d:/mozilla_src/mozilla/embedding/qa/testembed
 193         5) cd components                          // components directory
 194         6) Copy the makefile.in file and call it makefile. Place in same directory.
 195         7) Change the top few lines in 'makefile' to indicate local pathway. Example:
 196                 DEPTH           = ../../../..
 197                 topsrcdir    = d:/mozilla_src/mozilla
 198                 srcdir       = d:/mozilla_src/mozilla/embedding/qa/testembed/components
 199                 VPATH        = d:/mozilla_src/mozilla/embedding/qa/testembed/components
 200         8) make                                 // compile 'makefile.in' in components
 201         9) cd ..                                // return to testembed folder
 202         10) make                                // compile 'makefile.in' in testembed
 203         11) cd ../../../dist/bin/               // navigate to the bin dir
 204         12) testembed.exe                       // run testEmbed.exe
 205
 206         note: if 'make' doesn't work above, try 'make -f makefile.in'
 207
 208 A few suggestions:
 209         1) Don't run nsIWebNavigation tests after turning on the Web
 210         Progress listener (from Tests menu). This will create all types
 211         of listener msgs in your logfile and display many msgs on the
 212         screen.
 213         2) Best way to use web progress listener is to turn it on (from
 214         the Tests menu)then change URL . Change a few more urls and
 215         monitor the output.
 216         3) Before running nsISHistory interface tests, load 1-2 urls.
 217         That will create a session history. The same applies for the
 218         nsIWebNavigation interfaces tests. One loaded url will enable
 219         back/forward navigation.
 220         4) nsIUriContentListener is registered from the "Tests" >
 221         "Add urIContentListener" menu. There are submenu items for different options.