Autopilot

Merge lp:~fgimenez/autopilot/doc-nitpicks into lp:autopilot

doc-nitpicks
Merge into trunk

Proposed by Federico Gimenez on 2015-04-17

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

Commit message

Doc nitpicks

Description of the change

Doc nitpicks

lp:~fgimenez/autopilot/doc-nitpicks updated on 2015-04-17

552. By Federico Gimenez on 2015-04-17: fixed number of nodes selected

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2015-04-17:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/autopilot-ci/1045/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2015-04-17:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/autopilot-ci/1046/rebuild

review: Needs Fixing (continuous-integration)

Revision history for this message

Leo Arias (elopio) on 2015-04-17:

review: Approve

lp:~fgimenez/autopilot/doc-nitpicks updated on 2015-04-23

553. By Federico Gimenez on 2015-04-17: removed reduntant parentheses
554. By Federico Gimenez on 2015-04-23: Line wrapped according to pep8

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2015-04-23:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/autopilot-ci/1047/rebuild

review: Needs Fixing (continuous-integration)

Unmerged revisions

554. By Federico Gimenez on 2015-04-23: Line wrapped according to pep8
553. By Federico Gimenez on 2015-04-17: removed reduntant parentheses
552. By Federico Gimenez on 2015-04-17: fixed number of nodes selected
551. By Federico Gimenez on 2015-04-17: more doc nitpicks
550. By Federico Gimenez on 2015-03-27: fixed indentation
549. By Federico Gimenez on 2015-03-27: doc nitpicks

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk

Subscribers

People subscribed via source and target branches

to all changes:

Autopilot Hackers

Chris Gagnon

Federico Gimenez

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	a -> d;
6	}
7
8	-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.
9	+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
11	Relative Queries
12	++++++++++++++++
13
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	Q. What type of applications can autopilot test?
19	================================================
20
21	-Autopilot works with severall different types of applications, including:
22	+Autopilot works with several different types of applications, including:
23	* The Unity desktop shell.
24	* Gtk 2 & 3 applications.
25	* Qt4, Qt5, and Qml applications.
26	@@ -61,8 +61,8 @@
27	* 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
29	self.assertThat(save_win.title, Eventually(Equals("Save Document")))
30	- self.assertThat(save_win.visible, Equals(True))
31	- self.assertThat(save_win.has_focus, Equals(True))
32	+ self.assertTrue(save_win.visible)
33	+ self.assertTrue(save_win.has_focus)
34
35	* 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
37	@@ -80,7 +80,7 @@
38	self.assertThat(self.app.print_dialog.open, Eventually(Equals(True)))
39	self.keyboard.press_and_release('Enter')
40	# ensure something was sent to our faked printer:
41	- self.assertThat(self.fake_printer.documents_printed, Equals(1))
42	+ self.assertEqual(self.fake_printer.documents_printed, 1)
43
44	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
46	@@ -134,7 +134,7 @@
47	keyboard = Keyboard.create('OSK')
48	with keyboard.focused_type(text_area) as kb:
49	kb.type("Hello World.")
50	- self.assertThat(text_area.text, Equals("Hello World"))
51	+ self.assertEqual(text_area.text, "Hello World")
52	# At this point now the OSK has been swiped away.
53	self.assertThat()
54
55
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	text_win = self.open_new_application_window("Text Editor", maximized=True)
61
62	self.assertTrue(text_win.is_maximized)
63	- self.assertThat(self.panel.title, Equals(text_win.title))
64	+ self.assertEqual(self.panel.title, text_win.title)
65	sleep(.25)
66
67	calc_win = self.open_new_application_window("Calculator")
68	- self.assertThat(self.panel.title, Equals(calc_win.application.name))
69	+ self.assertEqual(self.panel.title, calc_win.application.name)
70
71	icon = self.launcher.model.get_icon_by_desktop_id(text_win.application.desktop_file)
72	launcher = self.launcher.get_launcher_for_monitor(self.panel_monitor)
73	launcher.click_launcher_icon(icon)
74
75	self.assertTrue(text_win.is_focused)
76	- self.assertThat(self.panel.title, Equals(text_win.title))
77	+ self.assertEqual(self.panel.title, text_win.title)
78
79	This test can be simplified into the following:
80
81	@@ -150,7 +150,7 @@
82	launcher.click_launcher_icon(icon)
83
84	self.assertTrue(text_win.is_focused)
85	- self.assertThat(self.panel.title, Equals(text_win.title))
86	+ self.assertEqual(self.panel.title, text_win.title)
87
88	Here's what we changed:
89
90	@@ -168,8 +168,7 @@
91	2. Avoid words like "should" in favor of stronger words like "must".
92	3. Contain a one-line summary of the test.
93
94	-Additionally, they should:
95	- 1. Include the launchpad bug number (if applicable).
96	+Additionally, they should include the launchpad bug number (if applicable).
97
98	Good Example:
99
100	@@ -308,7 +307,7 @@
101	sleep(2)
102	self.keyboard.press_and_release("Alt+F4")
103	sleep(2)
104	- self.assertThat(self.dash.visible, Equals(False))
105	+ self.assertFalse(self.dash.visible)
106
107	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
109
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
115	def test_empty_string_returns_no_results(self):
116	self.dictionary_app.enter_search_term("")
117	- self.assertThat(len(self.dictionary_app.results), Equals(0))
118	+ self.assertEqual(len(self.dictionary_app.results), 0)
119
120	def test_whitespace_string_returns_no_results(self):
121	self.dictionary_app.enter_search_term(" \t ")
122	- self.assertThat(len(self.dictionary_app.results), Equals(0))
123	+ self.assertEqual(len(self.dictionary_app.results), 0)
124
125	def test_punctuation_string_returns_no_results(self):
126	self.dictionary_app.enter_search_term(".-?<>{}[]")
127	- self.assertThat(len(self.dictionary_app.results), Equals(0))
128	+ self.assertEqual(len(self.dictionary_app.results), 0)
129
130	def test_garbage_string_returns_no_results(self):
131	self.dictionary_app.enter_search_term("ljdzgfhdsgjfhdgjh")
132	- self.assertThat(len(self.dictionary_app.results), Equals(0))
133	+ self.assertEqual(len(self.dictionary_app.results), 0)
134
135	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
137	@@ -84,7 +84,7 @@
138	)
139	for input in bad_strings:
140	self.dictionary_app.enter_search_term(input)
141	- self.assertThat(len(self.dictionary_app.results), Equals(0))
142	+ self.assertEqual(len(self.dictionary_app.results), 0)
143
144
145	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
148	def test_bad_strings_return_no_results(self):
149	self.dictionary_app.enter_search_term(self.input)
150	- self.assertThat(len(self.dictionary_app.results), Equals(0))
151	+ self.assertEqual(len(self.dictionary_app.results), 0)
152
153	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
155	@@ -122,7 +122,7 @@
156	Test Logging
157	============
158
159	-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.
160	+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
162	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
164	@@ -140,7 +140,7 @@
165	logger.warning("This is a warning")
166	logger.error("This is an error")
167
168	-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.
169	+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
171	Environment Patching
172	====================
173	@@ -536,10 +536,8 @@
174	class SpecificQLabel(CustomProxyObjectBase):
175
176	def validate_dbus_object(path, state):
177	- if (path.endswith('object_we_want') or
178	- state['some_property'] == 'desired_value'):
179	- return True
180	- return False
181	+ return (path.endswith('object_we_want') or
182	+ state['some_property'] == 'desired_value')
183
184	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
186	@@ -550,7 +548,7 @@
187	class TestCase(AutopilotTestCase):
188
189	def setUp(self):
190	- super(TestCase, self).setUp()
191	+ super().setUp()
192	self.app = self.launch_test_application(
193	'/path/to/the/application',
194	emulator_base=CustomProxyObjectBase)
195
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	autopilot/<projectname>/
201	autopilot/<projectname>/tests/
202
203	-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.
204	+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
206	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
208	@@ -51,7 +51,7 @@
209	class MyTests(AutopilotTestCase):
210
211	def setUp(self):
212	- super(MyTests, self).setUp()
213	+ super().setUp()
214	# This code gets run before every test!
215
216	def test_something(self):
217	@@ -89,7 +89,7 @@
218	A Simple Test
219	=============
220
221	-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::
222	+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
224	#!/usr/bin/env python
225
226	@@ -114,7 +114,6 @@
227
228	from autopilot.testcase import AutopilotTestCase
229	from os.path import abspath, dirname, join
230	- from testtools.matchers import Equals
231
232	class MainWindowTitleTests(AutopilotTestCase):
233
234	@@ -134,7 +133,7 @@
235	app_root = self.launch_application()
236	main_window = app_root.select_single('QMainWindow')
237
238	- self.assertThat(main_window.windowTitle, Equals("Hello World"))
239	+ self.assertEqual(main_window.windowTitle, "Hello World")
240
241
242	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	app_root = self.launch_application()
245	main_window = app_root.select_single('AutopilotHelloWorld')
246
247	- self.assertThat(main_window.windowTitle, Equals("Hello World"))
248	+ self.assertEqual(main_window.windowTitle, "Hello World")
249
250
251	class ButtonResponseTests(HelloWorldTestBase):
252	@@ -309,7 +308,7 @@
253
254	self.assertThat(response.text, Eventually(Equals('Response: Goodbye')))
255
256	-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``.
257	+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
259	.. otto:: Be careful when identifing user interface controls
260