1 ========================== |
|
2 Use Windmill with CubicWeb |
|
3 ========================== |
|
4 |
|
5 Windmill_ implements cross browser testing, in-browser recording and playback, |
|
6 and functionality for fast accurate debugging and test environment integration. |
|
7 |
|
8 .. _Windmill: http://www.getwindmill.com/ |
|
9 |
|
10 `Online features list <http://www.getwindmill.com/features>`_ is available. |
|
11 |
|
12 |
|
13 Installation |
|
14 ============ |
|
15 |
|
16 Windmill |
|
17 -------- |
|
18 |
|
19 You have to install Windmill manually for now. If you're using Debian, there is |
|
20 no binary package (`yet <http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=579109>`_). |
|
21 |
|
22 The simplest solution is to use a *setuptools/pip* command (for a clean |
|
23 environment, take a look to the `virtualenv |
|
24 <http://pypi.python.org/pypi/virtualenv>`_ project as well):: |
|
25 |
|
26 $ pip install windmill |
|
27 $ curl -O http://github.com/windmill/windmill/tarball/master |
|
28 |
|
29 However, the Windmill project doesn't release frequently. Our recommandation is |
|
30 to used the last snapshot of the Git repository:: |
|
31 |
|
32 $ git clone git://github.com/windmill/windmill.git HEAD |
|
33 $ cd windmill |
|
34 $ python setup.py develop |
|
35 |
|
36 Install instructions are `available <http://wiki.github.com/windmill/windmill/installing>`_. |
|
37 |
|
38 Be sure to have the windmill module in your PYTHONPATH afterwards:: |
|
39 |
|
40 $ python -c "import windmill" |
|
41 |
|
42 X dummy |
|
43 ------- |
|
44 |
|
45 In order to reduce unecessary system load from your test machines, It's |
|
46 recommended to use X dummy server for testing the Unix web clients, you need a |
|
47 dummy video X driver (as xserver-xorg-video-dummy package in Debian) coupled |
|
48 with a light X server as `Xvfb <http://en.wikipedia.org/wiki/Xvfb>`_. |
|
49 |
|
50 The dummy driver is a special driver available with the XFree86 DDX. To use |
|
51 the dummy driver, simply substitue it for your normal card driver in the |
|
52 Device section of your xorg.conf configuration file. For example, if you |
|
53 normally uses an ati driver, then you will have a Device section with |
|
54 Driver "ati" to let the X server know that you want it to load and use the |
|
55 ati driver; however, for these conformance tests, you would change that |
|
56 line to Driver "dummy" and remove any other ati specific options from the |
|
57 Device section. |
|
58 |
|
59 *From: http://www.x.org/wiki/XorgTesting* |
|
60 |
|
61 Then, you can run the X server with the following command :: |
|
62 |
|
63 $ /usr/bin/X11/Xvfb :1 -ac -screen 0 1280x1024x8 -fbdir /tmp |
|
64 |
|
65 |
|
66 Windmill usage |
|
67 ============== |
|
68 |
|
69 Record your use case |
|
70 -------------------- |
|
71 |
|
72 - start your instance manually |
|
73 - start Windmill_ with url site as last argument (read Usage_ or use *'-h'* |
|
74 option to find required command line arguments) |
|
75 - use the record button |
|
76 - click on save to obtain python code of your use case |
|
77 - copy the content to a new file in a *windmill* directory |
|
78 |
|
79 .. _Usage: http://wiki.github.com/windmill/windmill/running-tests |
|
80 |
|
81 If you are using firefox as client, consider the "firebug" option. |
|
82 |
|
83 If you have a running instance, you can refine the test by the *loadtest* windmill option:: |
|
84 |
|
85 $ windmill -m firebug loadtest=<test_file.py> <instance url> |
|
86 |
|
87 Or use the internal windmill shell to explore available commands:: |
|
88 |
|
89 $ windmill -m firebug shell <instance url> |
|
90 |
|
91 And enter python commands: |
|
92 |
|
93 .. sourcecode:: python |
|
94 |
|
95 >>> load_test(<your test file>) |
|
96 >>> run_test(<your test file>) |
|
97 |
|
98 |
|
99 |
|
100 Integrate Windmill tests into CubicWeb |
|
101 ====================================== |
|
102 |
|
103 Set environment |
|
104 --------------- |
|
105 |
|
106 You have to create a new unit test file and a `windmill` directory and copy all |
|
107 your windmill use case into it. |
|
108 |
|
109 .. sourcecode:: python |
|
110 |
|
111 # test_windmill.py |
|
112 |
|
113 # Run all scenarii found in windmill directory |
|
114 from cubicweb.devtools.cwwindmill import (CubicWebWindmillUseCase, |
|
115 unittest_main) |
|
116 |
|
117 if __name__ == '__main__': |
|
118 unittest_main() |
|
119 |
|
120 Run your tests |
|
121 -------------- |
|
122 |
|
123 You can easily run your windmill test suite through `pytest` or :mod:`unittest`. |
|
124 You have to copy a *test_windmill.py* file from :mod:`web.test`. |
|
125 |
|
126 To run your test series:: |
|
127 |
|
128 $ pytest test/test_windmill.py |
|
129 |
|
130 By default, CubicWeb will use **firefox** as the default browser and will try |
|
131 to run test instance server on localhost. In the general case, You've no need |
|
132 to change anything. |
|
133 |
|
134 Check :class:`cubicweb.devtools.cwwindmill.CubicWebWindmillUseCase` for |
|
135 Windmill configuration. You can edit windmill settings with following class attributes: |
|
136 |
|
137 * browser |
|
138 identification string (firefox|ie|safari|chrome) (firefox by default) |
|
139 * test_dir |
|
140 testing file path or directory (windmill directory under your unit case |
|
141 file by default) |
|
142 * edit_test |
|
143 load and edit test for debugging (False by default) |
|
144 |
|
145 Examples: |
|
146 |
|
147 .. sourcecode:: python |
|
148 |
|
149 browser = 'firefox' |
|
150 test_dir = osp.join(__file__, 'windmill') |
|
151 edit_test = False |
|
152 |
|
153 If you want to change cubicweb test server parameters, you can check class |
|
154 variables from :class:`CubicWebServerConfig` or inherit it with overriding the |
|
155 :attr:`configcls` attribute in :class:`CubicWebServerTC` :: |
|
156 |
|
157 .. sourcecode:: python |
|
158 |
|
159 class OtherCubicWebServerConfig(CubicWebServerConfig): |
|
160 port = 9999 |
|
161 |
|
162 class NewCubicWebServerTC(CubicWebServerTC): |
|
163 configcls = OtherCubicWebServerConfig |
|
164 |
|
165 For instance, CubicWeb framework windmill tests can be manually run by:: |
|
166 |
|
167 $ pytest web/test/test_windmill.py |
|
168 |
|
169 Edit your tests |
|
170 --------------- |
|
171 |
|
172 You can toggle the `edit_test` variable to enable test edition. |
|
173 |
|
174 But if you are using `pytest` as test runner, use the `-i` option directly. |
|
175 The test series will be loaded and you can run assertions step-by-step:: |
|
176 |
|
177 $ pytest -i test/test_windmill.py |
|
178 |
|
179 In this case, the `firebug` extension will be loaded automatically for you. |
|
180 |
|
181 Afterwards, don't forget to save your edited test into the right file (no autosave feature). |
|
182 |
|
183 Best practises |
|
184 -------------- |
|
185 |
|
186 Don't run another instance on the same port. You risk to silence some |
|
187 regressions (test runner will automatically fail in further versions). |
|
188 |
|
189 Start your use case by using an assert on the expected primary url page. |
|
190 Otherwise all your tests could fail without clear explanation of the used |
|
191 navigation. |
|
192 |
|
193 In the same location of the *test_windmill.py*, create a *windmill/* with your |
|
194 windmill recorded use cases. |
|
195 |
|
196 |
|
197 Caveats |
|
198 ======= |
|
199 |
|
200 File Upload |
|
201 ----------- |
|
202 |
|
203 Windmill can't do file uploads. This is a limitation of browser Javascript |
|
204 support / sandboxing, not of Windmill per se. It would be nice if there were |
|
205 some command that would prime the Windmill HTTP proxy to add a particular file |
|
206 to the next HTTP request that comes through, so that uploads could at least be |
|
207 faked. |
|
208 |
|
209 .. http://groups.google.com/group/windmill-dev/browse_thread/thread/cf9dc969722bd6bb/01aa18fdd652f7ff?lnk=gst&q=input+type+file#01aa18fdd652f7ff |
|
210 |
|
211 .. http://davisagli.com/blog/in-browser-integration-testing-with-windmill |
|
212 |
|
213 .. http://groups.google.com/group/windmill-dev/browse_thread/thread/b7bebcc38ed30dc7 |
|
214 |
|
215 |
|
216 Preferences |
|
217 =========== |
|
218 |
|
219 A *.windmill/prefs.py* could be used to redefine default configuration values. |
|
220 |
|
221 .. define CubicWeb preferences in the parent test case instead with a dedicated firefox profile |
|
222 |
|
223 For managing browser extensions, read `advanced topic chapter |
|
224 <http://wiki.github.com/windmill/windmill/advanced-topics>`_. |
|
225 |
|
226 More configuration examples could be seen in *windmill/conf/global_settings.py* |
|
227 as template. |
|
228 |
|
229 |
|