-
Notifications
You must be signed in to change notification settings - Fork 0
/
basic_documentation.txt
165 lines (140 loc) · 7.42 KB
/
basic_documentation.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
This file aims to describe MATS in terms of hi-level interface,
and describe some of it's desing decisions and fallbacks. More implementation
details are placed directly in code.
This document has following sections:
How to use it?
What MATS can do (now)?
Limitations
Architecture details
===============================================================================
How to use it?
1) do a custom build of Firefox, as described at:
https://developer.mozilla.org/En/Simple_Firefox_build
with a "enable-marionette" (included in MATS) patch applied. If it's outdated,
you should probably try checking
https://developer.mozilla.org/en/Marionette/Setup , and if that fails as well
- go IRC and ask someone at #a-team channel.
2) install Python 32 bits, don't try with 64 even if your OS is 64 bits.
Libraries that MATS rely on are not correctly updated to 64 bits.
3) install mozilla-central/testing/marionette/client (from mozilla-central)
4) install https://github.com/mozilla/mozbase or
mozilla-central/testing/mozbase (from mozilla-central), whichever is more
recent. Personally I used the one from github.
5) install setuptools from http://pypi.python.org/pypi/setuptools
6) install comtypes from
http://sourceforge.net/projects/comtypes/files/comtypes/0.6.2/ , I doubt it got
updated :), 32 bits of course. You can just download .exe and point it to
easy-install if you plan to run MATS inside virtualenv. This is the one that 64
bit version FAILS.
7) install lxml, by typing "easy_install lxml==2.3"
8) if I remember correctly, ctypes is part of standard installation right now.
If not - you need to install it as well, similarly to comtypes.
Uff, now you can run MATS in this environment. Set up winconfig.ini, go to
tests_msaa and type python test*_test.py
===============================================================================
What MATS can do (now)?
1) run Firefox/Nightly with Marionette enabled. It uses sandbox user profile.
2) stop Firefox, or wait for Firefox thread to stop (depending on test needs)
3) get full Accessible tree of Firefox. The tree inherits from
etree.ElementTree interface, as provided by lxml, plus methods defined in
AccessibleElement in accessible.py for every node. This allows you to navigate
a tree quickly via xpath, and do accessibility methods calls on nodes. Please
see limitations section of this document.
4) it is possible to get interactive shell while Firefox is running, if you
want to test interactively (useful in tests development and debugging).
See pyshell.py file for details.
5) whatever Marionette can do, it's instantiated, connected and working if
MatsRunner.run() succeeds.
What was planned?
1) auto-updating accessible tree (by registering a event listener to
MatsController and selectively updating subtrees).
2) adding AtSpi, IA2 and possibly UIA interfaces some day.
3) more tests.
===============================================================================
Limitations:
1) there cannot be two instances of MatsRunner running in the same time, since
WindowsListener object is singleton, and no support for this situation were
added. If you really need this, you have to figure out how to bound
WinEventProc from windows_listener.py with a particular WindowsListener
instance, and remove singleton pattern. This is not "mission impossible", it
should be possible to identify WindowsListener instance from _WinEventHook
argument.
2) accessible_tree also uses singleton pattern for now, since for compatibility
with lxml a mapping between xml <accesible> nodes and os-specific non-string
reference to Accessible object is needed. This was not needed before
lxml was introduced (you can try checking older versions of accessilbe.py and
accessible_msaa.py on github). Mapping is set between integer "mapping"
attribute in xml <accessible> nodes and (node, id) pairs in python. See
accessible.py and accessible_msaa.py for even more details.
3) accessible tree refreshing is not implemented now (June 14, 2012, this may
change yet)
===============================================================================
Architecture details
Files:
event.py
a very thin wrapper around whatever data MSAA returns. No serious
processing were implemented yet.
gef_config.py
implements get_config(config_file) method, which ensures that MATS config
is sane. See file header for details.
firefox_thread.py
implements FirefoxThread which is responsible for running Firefox via
MozBase, and does some user's profile setup to activate Marionette. Also,
it registers dummy FirefoxThreadLogger that sends all Firefox stdout into
abyss. Change FirefoxThreadLogger.__call__ method if you need it for some
reason.
mats_controller.py
chooses among available controllers judging on operating system used.
Import controller from here
mats_base_controller.py
provides "Not implemented" messages for subclasses :)
mats_msaa_controller.py
Implements a MSAA controller, that informs listeners on new messages.
Calling listeners can be paused and resumed, and messages queue can be
emptied without calling listeners. It is very important for test
reliability to clean message queue before taking action that is supposed to
trigger a OS message - otherwise, you can get a false positive.
I did my best to make it thread safe, the only application of it now can be
seen in mats_runner.py, method wait_for_event.
mats_atspi_controller.py
dummy file, never implemented
pyshell.py
a debugging tool. RunShellHere is pretty self explanatory, just put into
"env" dictionary whatever objects you want to expose to embedded
interactive shell. fall() and falle() methods prints call stack of
an exception, the latter also starts interactive shell.
SuperHandler is a dummy class that pretends to have every single method
implemented. That is useful if you try to investigate what a binary library
does with an object. Yes, I debugged binaries. No, it didn't go well.
winconstants.py
name says it all: constants specific to Windows OS. Sources in comments.
windows_listener.py
implements WindowsListener object, that is not a thread. It just wraps all
c-style system function calls. Singleton object, see Limitations section
for details.
winutils.py
some wrappers around Windows API methods that MatsController relies on.
Names are self explanatory. The active waiting was discussed in bugzilla
and over e-mail, but no alternative solution was found.
accessible.py
defines AccessibleElement and AccessibleTree basing on lxml classes.
AccessibleElement implements custom _init() method to achieve bounding of
os-specific data to xml nodes that are re-constructed via C-proxy.
See http://lxml.de/element_classes.html#element-initialization for details.
accessible_msaa.py
provides AccessibleElement and AccessibleTree constructors from MSAA.
A lot of COM to python code glue is here.
Threads:
There are multiple threads in this project. Fortunately, they form a clear call
tree - each thread is constructed and destroyed by the same owner thread, and
ownership (that never changes) presents as follows:
MatsRunner (object, not thread)
FirefoxThread (thread)
runs Firefox/Nightly via MozBase components. It also sets MozProfile to
activate Marionette by default
MatsController (thread)
listens to system events, and calls event listeners
Each thread exposes (along with obvious start() method) methods:
stop() - stops the thread, should be called only by thread owner
wait_for_ready() - waits until entry protocol of run() is finished, and thread
object is ready to receive further commands