← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/embedding/qa/testembed/README.TXT

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

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