1
=== modified file 'docs/appendix/protocol.rst'
2
--- docs/appendix/protocol.rst	2013-10-28 22:07:57 +0000
3
+++ docs/appendix/protocol.rst	2015-04-23 08:35:00 +0000
4
@@ -88,7 +88,7 @@
5
88
      a -> d;
88
      a -> d;
6
89
   }
89
   }
7
90
90
9
91
a query of ``/foo/bar`` will select two objects. This is allowed, but not always what we want. There are several ways to avoid this, they will be covered later in this document.
91
a query of ``/foo/bar`` will select three objects. This is allowed, but not always what we want. There are several ways to avoid this, they will be covered later in this document.
10
92
92
11
93
Relative Queries
93
Relative Queries
12
94
++++++++++++++++
94
++++++++++++++++
13
95
95
14
=== modified file 'docs/faq/faq.rst'
15
--- docs/faq/faq.rst	2015-01-25 23:08:51 +0000
16
+++ docs/faq/faq.rst	2015-04-23 08:35:00 +0000
17
@@ -37,7 +37,7 @@
18
37
Q. What type of applications can autopilot test?
37
Q. What type of applications can autopilot test?
19
38
================================================
38
================================================
20
39
39
22
40
Autopilot works with severall different types of applications, including:
40
Autopilot works with several different types of applications, including:
23
41
 * The Unity desktop shell.
41
 * The Unity desktop shell.
24
42
 * Gtk 2 & 3 applications.
42
 * Gtk 2 & 3 applications.
25
43
 * Qt4, Qt5, and Qml applications.
43
 * Qt4, Qt5, and Qml applications.
26
@@ -61,8 +61,8 @@
27
61
* Some features require several assertions to prove that the feature is working correctly. For example, you may wish to verify that the 'Save' dialog box opens correctly, using the following code::
61
* Some features require several assertions to prove that the feature is working correctly. For example, you may wish to verify that the 'Save' dialog box opens correctly, using the following code::
28
62
62
29
63
    self.assertThat(save_win.title, Eventually(Equals("Save Document")))
63
    self.assertThat(save_win.title, Eventually(Equals("Save Document")))
32
64
    self.assertThat(save_win.visible, Equals(True))
64
    self.assertTrue(save_win.visible)
33
65
    self.assertThat(save_win.has_focus, Equals(True))
65
    self.assertTrue(save_win.has_focus)
34
66
66
35
67
* Some tests need to wait for the application to respond to user input before the test continues. The easiest way to do this is to use the :class:`~autopilot.matchers.Eventually` matcher in the middle of your interaction with the application. For example, if testing the `Firefox <http://www.mozilla.org/en-US/>`_ browsers ability to print a certain web comic, we might produce a test that looks similar to this::
67
* Some tests need to wait for the application to respond to user input before the test continues. The easiest way to do this is to use the :class:`~autopilot.matchers.Eventually` matcher in the middle of your interaction with the application. For example, if testing the `Firefox <http://www.mozilla.org/en-US/>`_ browsers ability to print a certain web comic, we might produce a test that looks similar to this::
36
68
68
37
@@ -80,7 +80,7 @@
38
80
        self.assertThat(self.app.print_dialog.open, Eventually(Equals(True)))
80
        self.assertThat(self.app.print_dialog.open, Eventually(Equals(True)))
39
81
        self.keyboard.press_and_release('Enter')
81
        self.keyboard.press_and_release('Enter')
40
82
        # ensure something was sent to our faked printer:
82
        # ensure something was sent to our faked printer:
42
83
        self.assertThat(self.fake_printer.documents_printed, Equals(1))
83
        self.assertEqual(self.fake_printer.documents_printed, 1)
43
84
84
44
85
In general, autopilot tests are more relaxed about the 'one assertion per test' rule. However, care should still be taken to produce tests that are as small and understandable as possible.
85
In general, autopilot tests are more relaxed about the 'one assertion per test' rule. However, care should still be taken to produce tests that are as small and understandable as possible.
45
86
86
46
@@ -134,7 +134,7 @@
47
134
  keyboard = Keyboard.create('OSK')
134
  keyboard = Keyboard.create('OSK')
48
135
  with keyboard.focused_type(text_area) as kb:
135
  with keyboard.focused_type(text_area) as kb:
49
136
      kb.type("Hello World.")
136
      kb.type("Hello World.")
51
137
      self.assertThat(text_area.text, Equals("Hello World"))
137
      self.assertEqual(text_area.text, "Hello World")
52
138
  # At this point now the OSK has been swiped away.
138
  # At this point now the OSK has been swiped away.
53
139
  self.assertThat()
139
  self.assertThat()
54
140
140
55
141
141
56
=== modified file 'docs/guides/good_tests.rst'
57
--- docs/guides/good_tests.rst	2015-01-22 16:18:06 +0000
58
+++ docs/guides/good_tests.rst	2015-04-23 08:35:00 +0000
59
@@ -123,18 +123,18 @@
60
123
        text_win = self.open_new_application_window("Text Editor", maximized=True)
123
        text_win = self.open_new_application_window("Text Editor", maximized=True)
61
124
124
62
125
        self.assertTrue(text_win.is_maximized)
125
        self.assertTrue(text_win.is_maximized)
64
126
        self.assertThat(self.panel.title, Equals(text_win.title))
126
        self.assertEqual(self.panel.title, text_win.title)
65
127
        sleep(.25)
127
        sleep(.25)
66
128
128
67
129
        calc_win = self.open_new_application_window("Calculator")
129
        calc_win = self.open_new_application_window("Calculator")
69
130
        self.assertThat(self.panel.title, Equals(calc_win.application.name))
130
        self.assertEqual(self.panel.title, calc_win.application.name)
70
131
131
71
132
        icon = self.launcher.model.get_icon_by_desktop_id(text_win.application.desktop_file)
132
        icon = self.launcher.model.get_icon_by_desktop_id(text_win.application.desktop_file)
72
133
        launcher = self.launcher.get_launcher_for_monitor(self.panel_monitor)
133
        launcher = self.launcher.get_launcher_for_monitor(self.panel_monitor)
73
134
        launcher.click_launcher_icon(icon)
134
        launcher.click_launcher_icon(icon)
74
135
135
75
136
        self.assertTrue(text_win.is_focused)
136
        self.assertTrue(text_win.is_focused)
77
137
        self.assertThat(self.panel.title, Equals(text_win.title))
137
        self.assertEqual(self.panel.title, text_win.title)
78
138
138
79
139
This test can be simplified into the following:
139
This test can be simplified into the following:
80
140
140
81
@@ -150,7 +150,7 @@
82
150
        launcher.click_launcher_icon(icon)
150
        launcher.click_launcher_icon(icon)
83
151
151
84
152
        self.assertTrue(text_win.is_focused)
152
        self.assertTrue(text_win.is_focused)
86
153
        self.assertThat(self.panel.title, Equals(text_win.title))
153
        self.assertEqual(self.panel.title, text_win.title)
87
154
154
88
155
Here's what we changed:
155
Here's what we changed:
89
156
156
90
@@ -168,8 +168,7 @@
91
168
 2. Avoid words like "should" in favor of stronger words like "must".
168
 2. Avoid words like "should" in favor of stronger words like "must".
92
169
 3. Contain a one-line summary of the test.
169
 3. Contain a one-line summary of the test.
93
170
170
96
171
Additionally, they should:
171
Additionally, they should include the launchpad bug number (if applicable).
95
172
 1. Include the launchpad bug number (if applicable).
97
173
172
98
174
**Good Example:**
173
**Good Example:**
99
175
174
100
@@ -308,7 +307,7 @@
101
308
        sleep(2)
307
        sleep(2)
102
309
        self.keyboard.press_and_release("Alt+F4")
308
        self.keyboard.press_and_release("Alt+F4")
103
310
        sleep(2)
309
        sleep(2)
105
311
        self.assertThat(self.dash.visible, Equals(False))
310
        self.assertFalse(self.dash.visible)
106
312
311
107
313
This test uses two ``sleep`` calls. The first makes sure the dash has had time to open before the test continues, and the second makes sure that the dash has had time to respond to our key presses before we start testing things.
312
This test uses two ``sleep`` calls. The first makes sure the dash has had time to open before the test continues, and the second makes sure that the dash has had time to respond to our key presses before we start testing things.
108
314
313
109
315
314
110
=== modified file 'docs/tutorial/advanced_autopilot.rst'
111
--- docs/tutorial/advanced_autopilot.rst	2015-01-23 09:47:02 +0000
112
+++ docs/tutorial/advanced_autopilot.rst	2015-04-23 08:35:00 +0000
113
@@ -58,19 +58,19 @@
114
58
58
115
59
        def test_empty_string_returns_no_results(self):
59
        def test_empty_string_returns_no_results(self):
116
60
            self.dictionary_app.enter_search_term("")
60
            self.dictionary_app.enter_search_term("")
118
61
            self.assertThat(len(self.dictionary_app.results), Equals(0))
61
            self.assertEqual(len(self.dictionary_app.results), 0)
119
62
62
120
63
        def test_whitespace_string_returns_no_results(self):
63
        def test_whitespace_string_returns_no_results(self):
121
64
            self.dictionary_app.enter_search_term(" \t ")
64
            self.dictionary_app.enter_search_term(" \t ")
123
65
            self.assertThat(len(self.dictionary_app.results), Equals(0))
65
            self.assertEqual(len(self.dictionary_app.results), 0)
124
66
66
125
67
        def test_punctuation_string_returns_no_results(self):
67
        def test_punctuation_string_returns_no_results(self):
126
68
            self.dictionary_app.enter_search_term(".-?<>{}[]")
68
            self.dictionary_app.enter_search_term(".-?<>{}[]")
128
69
            self.assertThat(len(self.dictionary_app.results), Equals(0))
69
            self.assertEqual(len(self.dictionary_app.results), 0)
129
70
70
130
71
        def test_garbage_string_returns_no_results(self):
71
        def test_garbage_string_returns_no_results(self):
131
72
            self.dictionary_app.enter_search_term("ljdzgfhdsgjfhdgjh")
72
            self.dictionary_app.enter_search_term("ljdzgfhdsgjfhdgjh")
133
73
            self.assertThat(len(self.dictionary_app.results), Equals(0))
73
            self.assertEqual(len(self.dictionary_app.results), 0)
134
74
74
135
75
The main problem here is that there's a lot of typing in order to change exactly one thing (and this hypothetical test is deliberately short, to ease clarity. Imagine a 100 line test case!). Another approach is to make the entire thing one large test (*don't do this either*)::
75
The main problem here is that there's a lot of typing in order to change exactly one thing (and this hypothetical test is deliberately short, to ease clarity. Imagine a 100 line test case!). Another approach is to make the entire thing one large test (*don't do this either*)::
136
76
76
137
@@ -84,7 +84,7 @@
138
84
                )
84
                )
139
85
            for input in bad_strings:
85
            for input in bad_strings:
140
86
                self.dictionary_app.enter_search_term(input)
86
                self.dictionary_app.enter_search_term(input)
142
87
                self.assertThat(len(self.dictionary_app.results), Equals(0))
87
                self.assertEqual(len(self.dictionary_app.results), 0)
143
88
88
144
89
89
145
90
This approach makes it easier to add new input strings, but what happens when just one of the input strings stops working? It becomes very hard to find out which input string is broken, and the first string that breaks will prevent the rest of the test from running, since tests stop running when the first assertion fails.
90
This approach makes it easier to add new input strings, but what happens when just one of the input strings stops working? It becomes very hard to find out which input string is broken, and the first string that breaks will prevent the rest of the test from running, since tests stop running when the first assertion fails.
146
@@ -102,7 +102,7 @@
147
102
102
148
103
        def test_bad_strings_return_no_results(self):
103
        def test_bad_strings_return_no_results(self):
149
104
            self.dictionary_app.enter_search_term(self.input)
104
            self.dictionary_app.enter_search_term(self.input)
151
105
            self.assertThat(len(self.dictionary_app.results), Equals(0))
105
            self.assertEqual(len(self.dictionary_app.results), 0)
152
106
106
153
107
Autopilot will run the ``test_bad_strings_return_no_results`` once for each scenario. On each test, the values from the scenario dictionary will be mapped to attributes of the test case class. In this example, that means that the 'input' dictionary item will be mapped to ``self.input``. Using scenarios has several benefits over either of the other strategies outlined above:
107
Autopilot will run the ``test_bad_strings_return_no_results`` once for each scenario. On each test, the values from the scenario dictionary will be mapped to attributes of the test case class. In this example, that means that the 'input' dictionary item will be mapped to ``self.input``. Using scenarios has several benefits over either of the other strategies outlined above:
154
108
108
155
@@ -122,7 +122,7 @@
156
122
Test Logging
122
Test Logging
157
123
============
123
============
158
124
124
160
125
Autopilot integrates the `python logging framework <http://docs.python.org/2/library/logging.html>`_ into the :class:`~autopilot.testcase.AutopilotTestCase` class. Various autopilot components write log messages to the logging framework, and all these log messages are attached to each test result when the test completes. By default, these log messages are shown when a test fails, or if autopilot is run with the ``-v`` option.
125
Autopilot integrates the `python logging framework <http://docs.python.org/3/library/logging.html>`_ into the :class:`~autopilot.testcase.AutopilotTestCase` class. Various autopilot components write log messages to the logging framework, and all these log messages are attached to each test result when the test completes. By default, these log messages are shown when a test fails, or if autopilot is run with the ``-v`` option.
161
126
126
162
127
Test authors are encouraged to write to the python logging framework whenever doing so would make failing tests clearer. To do this, there are a few simple steps to follow:
127
Test authors are encouraged to write to the python logging framework whenever doing so would make failing tests clearer. To do this, there are a few simple steps to follow:
163
128
128
164
@@ -140,7 +140,7 @@
165
140
    logger.warning("This is a warning")
140
    logger.warning("This is a warning")
166
141
    logger.error("This is an error")
141
    logger.error("This is an error")
167
142
142
169
143
For more information on the various logging levels, see the `python documentation on Logger objects <http://docs.python.org/2/library/logging.html#logger-objects>`_. All messages logged in this way will be picked up by the autopilot test runner. This is a valuable tool when debugging failing tests.
143
For more information on the various logging levels, see the `python documentation on Logger objects <http://docs.python.org/3/library/logging.html#logger-objects>`_. All messages logged in this way will be picked up by the autopilot test runner. This is a valuable tool when debugging failing tests.
170
144
144
171
145
Environment Patching
145
Environment Patching
172
146
====================
146
====================
173
@@ -536,10 +536,8 @@
174
536
    class SpecificQLabel(CustomProxyObjectBase):
536
    class SpecificQLabel(CustomProxyObjectBase):
175
537
537
176
538
        def validate_dbus_object(path, state):
538
        def validate_dbus_object(path, state):
181
539
            if (path.endswith('object_we_want') or
539
            return (path.endswith('object_we_want') or 
182
540
                    state['some_property'] == 'desired_value'):
540
                state['some_property'] == 'desired_value')
179
541
                return True
180
542
            return False
183
543
541
184
544
This method should return True if the object matches this custom proxy class, and False otherwise.  If more than one custom proxy class matches an object, a :exc:`ValueError` will be raised at runtime.
542
This method should return True if the object matches this custom proxy class, and False otherwise.  If more than one custom proxy class matches an object, a :exc:`ValueError` will be raised at runtime.
185
545
543
186
@@ -550,7 +548,7 @@
187
550
    class TestCase(AutopilotTestCase):
548
    class TestCase(AutopilotTestCase):
188
551
549
189
552
        def setUp(self):
550
        def setUp(self):
191
553
            super(TestCase, self).setUp()
551
            super().setUp()
192
554
            self.app = self.launch_test_application(
552
            self.app = self.launch_test_application(
193
555
                '/path/to/the/application',
553
                '/path/to/the/application',
194
556
                emulator_base=CustomProxyObjectBase)
554
                emulator_base=CustomProxyObjectBase)
195
557
555
196
=== modified file 'docs/tutorial/getting_started.rst'
197
--- docs/tutorial/getting_started.rst	2015-02-19 20:26:30 +0000
198
+++ docs/tutorial/getting_started.rst	2015-04-23 08:35:00 +0000
199
@@ -12,7 +12,7 @@
200
12
	autopilot/<projectname>/
12
	autopilot/<projectname>/
201
13
	autopilot/<projectname>/tests/
13
	autopilot/<projectname>/tests/
202
14
14
204
15
The ``autopilot`` folder can be anywhere within your project's source tree. It will likely contain a `setup.py <http://docs.python.org/3/distutils/setupscript.html>`_ file.
15
The ``autopilot`` folder can be anywhere within your project's source tree. It will likely contain a `setup.py <https://setuptools.pypa.io/en/latest/setuptools.html>`_ file.
205
16
16
206
17
The ``autopilot/<projectname>/`` folder is the base package for your autopilot tests. This folder, and all child folders, are python packages, and so must contain an `__init__.py file <http://docs.python.org/3/tutorial/modules.html#packages>`_. If you ever find yourself writing custom proxy classes (This is an advanced topic, and is covered here: :ref:`custom_proxy_classes`), they should be imported from this top-level package.
17
The ``autopilot/<projectname>/`` folder is the base package for your autopilot tests. This folder, and all child folders, are python packages, and so must contain an `__init__.py file <http://docs.python.org/3/tutorial/modules.html#packages>`_. If you ever find yourself writing custom proxy classes (This is an advanced topic, and is covered here: :ref:`custom_proxy_classes`), they should be imported from this top-level package.
207
18
18
208
@@ -51,7 +51,7 @@
209
51
	class MyTests(AutopilotTestCase):
51
	class MyTests(AutopilotTestCase):
210
52
52
211
53
		def setUp(self):
53
		def setUp(self):
213
54
			super(MyTests, self).setUp()
54
			super().setUp()
214
55
			# This code gets run before every test!
55
			# This code gets run before every test!
215
56
56
216
57
		def test_something(self):
57
		def test_something(self):
217
@@ -89,7 +89,7 @@
218
89
A Simple Test
89
A Simple Test
219
90
=============
90
=============
220
91
91
222
92
To demonstrate the material covered so far, this selection will outline a simple application, and a single test for it. Instead of testing a third-party application, we will write the simplest possible application in Python and Qt4. The application, named 'testapp.py', is listed below::
92
To demonstrate the material covered so far, this section will outline a simple application, and a single test for it. Instead of testing a third-party application, we will write the simplest possible application in Python and Qt4. The application, named 'testapp.py', is listed below::
223
93
93
224
94
	#!/usr/bin/env python
94
	#!/usr/bin/env python
225
95
95
226
@@ -114,7 +114,6 @@
227
114
114
228
115
	from autopilot.testcase import AutopilotTestCase
115
	from autopilot.testcase import AutopilotTestCase
229
116
	from os.path import abspath, dirname, join
116
	from os.path import abspath, dirname, join
230
117
	from testtools.matchers import Equals
231
118
117
232
119
	class MainWindowTitleTests(AutopilotTestCase):
118
	class MainWindowTitleTests(AutopilotTestCase):
233
120
119
234
@@ -134,7 +133,7 @@
235
134
	        app_root = self.launch_application()
133
	        app_root = self.launch_application()
236
135
	        main_window = app_root.select_single('QMainWindow')
134
	        main_window = app_root.select_single('QMainWindow')
237
136
135
239
137
	        self.assertThat(main_window.windowTitle, Equals("Hello World"))
136
	        self.assertEqual(main_window.windowTitle, "Hello World")
240
138
137
241
139
138
242
140
Note that we have made the test method as readable as possible by hiding the complexities of finding the full path to the application we want to test. Of course, if you can guarantee that the application is in :envvar:`PATH`, then this step becomes a lot simpler.
139
Note that we have made the test method as readable as possible by hiding the complexities of finding the full path to the application we want to test. Of course, if you can guarantee that the application is in :envvar:`PATH`, then this step becomes a lot simpler.
243
@@ -283,7 +282,7 @@
244
283
	        app_root = self.launch_application()
282
	        app_root = self.launch_application()
245
284
	        main_window = app_root.select_single('AutopilotHelloWorld')
283
	        main_window = app_root.select_single('AutopilotHelloWorld')
246
285
284
248
286
	        self.assertThat(main_window.windowTitle, Equals("Hello World"))
285
	        self.assertEqual(main_window.windowTitle, "Hello World")
249
287
286
250
288
287
251
289
	class ButtonResponseTests(HelloWorldTestBase):
288
	class ButtonResponseTests(HelloWorldTestBase):
252
@@ -309,7 +308,7 @@
253
309
308
254
310
	        self.assertThat(response.text, Eventually(Equals('Response: Goodbye')))
309
	        self.assertThat(response.text, Eventually(Equals('Response: Goodbye')))
255
311
310
257
312
In addition to the new class, ``ButtonResponseTests``, you'll notice a few other changes. First, two new import lines were added to support the new tests. Next, the existing ``MainWindowTitleTests`` class was refactored to subclass from a base class, ``HelloWorldTestBase``. The base class contains the ``launch_application`` method which is used for all test cases. Finally, the object type of the main window changed from ``QMainWindow`` to ``AutopilotHelloWorld``. The change in object type is a result of our test application being refactored into a class called ``AutopilotHelloWorld``.
311
In addition to the new class, ``ButtonResponseTests``, you'll notice a few other changes. First, three new import lines were added to support the new tests. Next, the existing ``MainWindowTitleTests`` class was refactored to subclass from a base class, ``HelloWorldTestBase``. The base class contains the ``launch_application`` method which is used for all test cases. Finally, the object type of the main window changed from ``QMainWindow`` to ``AutopilotHelloWorld``. The change in object type is a result of our test application being refactored into a class called ``AutopilotHelloWorld``.
258
313
312
259
314
.. otto:: **Be careful when identifing user interface controls**
313
.. otto:: **Be careful when identifing user interface controls**
260
315
314
Status:	Needs review
Proposed branch:	lp:~fgimenez/autopilot/doc-nitpicks
Merge into:	lp:autopilot
Diff against target:	259 lines (+29/-33) 5 files modified docs/appendix/protocol.rst (+1/-1) docs/faq/faq.rst (+5/-5) docs/guides/good_tests.rst (+6/-7) docs/tutorial/advanced_autopilot.rst (+11/-13) docs/tutorial/getting_started.rst (+6/-7)
To merge this branch:	bzr merge lp:~fgimenez/autopilot/doc-nitpicks
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
PS Jenkins bot	continuous-integration		Needs Fixing on 2015-04-23
Leo Arias (community)		2015-04-17	Approve on 2015-04-17
Review via email: mp+256632@code.launchpad.net