← Back to branch summary

~ubuntu-branches/ubuntu/quantal/enigmail/quantal-security

« back to all changes in this revision

Viewing changes to mozilla/testing/mozbase/manifestdestiny/README.md

  • Committer: Package Import Robot
  • Author(s): Chris Coulson
  • Date: 2013-09-13 16:02:15 UTC
  • mfrom: (0.12.16)
  • Revision ID: package-import@ubuntu.com-20130913160215-u3g8nmwa0pdwagwc
Tags: 2:1.5.2-0ubuntu0.12.10.1
* New upstream release v1.5.2 for Thunderbird 24

* Build enigmail using a stripped down Thunderbird 17 build system, as it's
  now quite difficult to build the way we were doing previously, with the
  latest Firefox build system
* Add debian/patches/no_libxpcom.patch - Don't link against libxpcom, as it
  doesn't exist anymore (but exists in the build system)
* Add debian/patches/use_sdk.patch - Use the SDK version of xpt.py and
  friends
* Drop debian/patches/ipc-pipe_rename.diff (not needed anymore)
* Drop debian/patches/makefile_depth.diff (not needed anymore)

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/testing/mozbase/manifestdestiny/README.md
 
1
Universal manifests for Mozilla test harnesses
 
2
 
 
3
# What is ManifestDestiny?
 
4
 
 
5
What ManifestDestiny gives you:
 
6
 
 
7
* manifests are ordered lists of tests
 
8
* tests may have an arbitrary number of key, value pairs
 
9
* the parser returns an ordered list of test data structures, which
 
10
  are just dicts with some keys.  For example, a test with no
 
11
  user-specified metadata looks like this:
 
12
 
 
13
    [{'path':
 
14
      '/home/jhammel/mozmill/src/ManifestDestiny/manifestdestiny/tests/testToolbar/testBackForwardButtons.js',
 
15
      'name': 'testToolbar/testBackForwardButtons.js', 'here':
 
16
      '/home/jhammel/mozmill/src/ManifestDestiny/manifestdestiny/tests',
 
17
      'manifest': '/home/jhammel/mozmill/src/ManifestDestiny/manifestdestiny/tests',}]
 
18
 
 
19
The keys displayed here (path, name, here, and manifest) are reserved
 
20
keys for ManifestDestiny and any consuming APIs.  You can add
 
21
additional key, value metadata to each test.
 
22
 
 
23
 
 
24
# Why have test manifests?
 
25
 
 
26
It is desirable to have a unified format for test manifests for testing
 
27
[mozilla-central](http://hg.mozilla.org/mozilla-central), etc.
 
28
 
 
29
* It is desirable to be able to selectively enable or disable tests based on platform or other conditions. This should be easy to do. Currently, since many of the harnesses just crawl directories, there is no effective way of disabling a test except for removal from mozilla-central
 
30
* It is desriable to do this in a universal way so that enabling and disabling tests as well as other tasks are easily accessible to a wider audience than just those intimately familiar with the specific test framework.
 
31
* It is desirable to have other metadata on top of the test. For instance, let's say a test is marked as skipped. It would be nice to give the reason why.
 
32
 
 
33
 
 
34
Most Mozilla test harnesses work by crawling a directory structure.
 
35
While this is straight-forward, manifests offer several practical
 
36
advantages::
 
37
 
 
38
* ability to turn a test off easily: if a test is broken on m-c
 
39
  currently, the only way to turn it off, generally speaking, is just
 
40
  removing the test.  Often this is undesirable, as if the test should
 
41
  be dismissed because other people want to land and it can't be
 
42
  investigated in real time (is it a failure? is the test bad? is no
 
43
  one around that knows the test?), then backing out a test is at best
 
44
  problematic.  With a manifest, a test may be disabled without
 
45
  removing it from the tree and a bug filed with the appropriate
 
46
  reason:
 
47
 
 
48
     [test_broken.js]
 
49
     disabled = https://bugzilla.mozilla.org/show_bug.cgi?id=123456
 
50
 
 
51
* ability to run different (subsets of) tests on different
 
52
  platforms. Traditionally, we've done a bit of magic or had the test
 
53
  know what platform it would or would not run on. With manifests, you
 
54
  can mark what platforms a test will or will not run on and change
 
55
  these without changing the test.
 
56
 
 
57
     [test_works_on_windows_only.js]
 
58
     run-if = os == 'win'
 
59
 
 
60
* ability to markup tests with metadata. We have a large, complicated,
 
61
  and always changing infrastructure.  key, value metadata may be used
 
62
  as an annotation to a test and appropriately curated and mined.  For
 
63
  instance, we could mark certain tests as randomorange with a bug
 
64
  number, if it were desirable.
 
65
 
 
66
* ability to have sane and well-defined test-runs. You can keep
 
67
  different manifests for different test runs and ``[include:]``
 
68
  (sub)manifests as appropriate to your needs.
 
69
 
 
70
 
 
71
# Manifest Format
 
72
 
 
73
Manifests are .ini file with the section names denoting the path
 
74
relative to the manifest:
 
75
 
 
76
    [foo.js]
 
77
    [bar.js]
 
78
    [fleem.js]
 
79
 
 
80
The sections are read in order. In addition, tests may include
 
81
arbitrary key, value metadata to be used by the harness.  You may also
 
82
have a `[DEFAULT]` section that will give key, value pairs that will
 
83
be inherited by each test unless overridden:
 
84
 
 
85
    [DEFAULT]
 
86
    type = restart
 
87
 
 
88
    [lilies.js]
 
89
    color = white
 
90
 
 
91
    [daffodils.js]
 
92
    color = yellow
 
93
    type = other
 
94
    # override type from DEFAULT
 
95
 
 
96
    [roses.js]
 
97
    color = red
 
98
 
 
99
You can also include other manifests:
 
100
 
 
101
    [include:subdir/anothermanifest.ini]
 
102
 
 
103
Manifests are included relative to the directory of the manifest with
 
104
the `[include:]` directive unless they are absolute paths.
 
105
 
 
106
 
 
107
# Data
 
108
 
 
109
Manifest Destiny gives tests as a list of dictionaries (in python
 
110
terms).
 
111
 
 
112
* path: full path to the test
 
113
* name: short name of the test; this is the (usually) relative path
 
114
  specified in the section name
 
115
* here: the parent directory of the manifest
 
116
* manifest: the path to the manifest containing the test
 
117
 
 
118
This data corresponds to a one-line manifest:
 
119
 
 
120
    [testToolbar/testBackForwardButtons.js]
 
121
 
 
122
If additional key, values were specified, they would be in this dict
 
123
as well.
 
124
 
 
125
Outside of the reserved keys, the remaining key, values
 
126
are up to convention to use.  There is a (currently very minimal)
 
127
generic integration layer in ManifestDestiny for use of all harnesses,
 
128
`manifestparser.TestManifest`.
 
129
For instance, if the 'disabled' key is present, you can get the set of
 
130
tests without disabled (various other queries are doable as well).
 
131
 
 
132
Since the system is convention-based, the harnesses may do whatever
 
133
they want with the data.  They may ignore it completely, they may use
 
134
the provided integration layer, or they may provide their own
 
135
integration layer.  This should allow whatever sort of logic is
 
136
desired.  For instance, if in yourtestharness you wanted to run only on
 
137
mondays for a certain class of tests:
 
138
 
 
139
    tests = []
 
140
    for test in manifests.tests:
 
141
        if 'runOnDay' in test:
 
142
           if calendar.day_name[calendar.weekday(*datetime.datetime.now().timetuple()[:3])].lower() == test['runOnDay'].lower():
 
143
               tests.append(test)
 
144
        else:
 
145
           tests.append(test)
 
146
 
 
147
To recap:
 
148
* the manifests allow you to specify test data
 
149
* the parser gives you this data
 
150
* you can use it however you want or process it further as you need
 
151
 
 
152
Tests are denoted by sections in an .ini file (see
 
153
http://hg.mozilla.org/automation/ManifestDestiny/file/tip/manifestdestiny/tests/mozmill-example.ini).
 
154
 
 
155
Additional manifest files may be included with an `[include:]` directive:
 
156
 
 
157
    [include:path-to-additional-file.manifest]
 
158
 
 
159
The path to included files is relative to the current manifest.
 
160
 
 
161
The `[DEFAULT]` section contains variables that all tests inherit from.
 
162
 
 
163
Included files will inherit the top-level variables but may override
 
164
in their own `[DEFAULT]` section.
 
165
 
 
166
 
 
167
# ManifestDestiny Architecture
 
168
 
 
169
There is a two- or three-layered approach to the ManifestDestiny
 
170
architecture, depending on your needs:
 
171
 
 
172
1. ManifestParser: this is a generic parser for .ini manifests that
 
173
facilitates the `[include:]` logic and the inheritence of
 
174
metadata. Despite the internal variable being called `self.tests`
 
175
(an oversight), this layer has nothing in particular to do with tests.
 
176
 
 
177
2. TestManifest: this is a harness-agnostic integration layer that is
 
178
test-specific. TestManifest faciliates `skip-if` and `run-if` logic.
 
179
 
 
180
3. Optionally, a harness will have an integration layer than inherits
 
181
from TestManifest if more harness-specific customization is desired at
 
182
the manifest level.
 
183
 
 
184
See the source code at https://github.com/mozilla/mozbase/tree/master/manifestdestiny
 
185
and
 
186
https://github.com/mozilla/mozbase/blob/master/manifestdestiny/manifestparser.py
 
187
in particular.
 
188
 
 
189
 
 
190
# Using Manifests
 
191
 
 
192
A test harness will normally call `TestManifest.active_tests`:
 
193
 
 
194
    def active_tests(self, exists=True, disabled=True, **tags):
 
195
 
 
196
The manifests are passed to the `__init__` or `read` methods with
 
197
appropriate arguments.  `active_tests` then allows you to select the
 
198
tests you want:
 
199
 
 
200
- exists : return only existing tests
 
201
- disabled : whether to return disabled tests; if not these will be
 
202
  filtered out; if True (the default), the `disabled` key of a
 
203
  test's metadata will be present and will be set to the reason that a
 
204
  test is disabled
 
205
- tags : keys and values to filter on (e.g. `os='linux'`)
 
206
 
 
207
`active_tests` looks for tests with `skip-if`
 
208
`run-if`.  If the condition is or is not fulfilled,
 
209
respectively, the test is marked as disabled.  For instance, if you
 
210
pass `**dict(os='linux')` as `**tags`, if a test contains a line
 
211
`skip-if = os == 'linux'` this test will be disabled, or
 
212
`run-if = os = 'win'` in which case the test will also be disabled.  It
 
213
is up to the harness to pass in tags appropriate to its usage.
 
214
 
 
215
 
 
216
# Creating Manifests
 
217
 
 
218
ManifestDestiny comes with a console script, `manifestparser create`, that
 
219
may be used to create a seed manifest structure from a directory of
 
220
files.  Run `manifestparser help create` for usage information.
 
221
 
 
222
 
 
223
# Copying Manifests
 
224
 
 
225
To copy tests and manifests from a source:
 
226
 
 
227
    manifestparser [options] copy from_manifest to_directory -tag1 -tag2 --key1=value1 key2=value2 ...
 
228
 
 
229
 
 
230
# Upating Tests
 
231
 
 
232
To update the tests associated with with a manifest from a source
 
233
directory:
 
234
 
 
235
    manifestparser [options] update manifest from_directory -tag1 -tag2 --key1=value1 --key2=value2 ...
 
236
 
 
237
 
 
238
# Usage example
 
239
 
 
240
Here is an example of how to create manifests for a directory tree and
 
241
update the tests listed in the manifests from an external source.
 
242
 
 
243
## Creating Manifests
 
244
 
 
245
Let's say you want to make a series of manifests for a given directory structure containing `.js` test files:
 
246
 
 
247
    testing/mozmill/tests/firefox/
 
248
    testing/mozmill/tests/firefox/testAwesomeBar/
 
249
    testing/mozmill/tests/firefox/testPreferences/
 
250
    testing/mozmill/tests/firefox/testPrivateBrowsing/
 
251
    testing/mozmill/tests/firefox/testSessionStore/
 
252
    testing/mozmill/tests/firefox/testTechnicalTools/
 
253
    testing/mozmill/tests/firefox/testToolbar/
 
254
    testing/mozmill/tests/firefox/restartTests
 
255
 
 
256
You can use `manifestparser create` to do this:
 
257
 
 
258
    $ manifestparser help create
 
259
    Usage: manifestparser.py [options] create directory <directory> <...>
 
260
 
 
261
         create a manifest from a list of directories
 
262
 
 
263
    Options:
 
264
      -p PATTERN, --pattern=PATTERN
 
265
                            glob pattern for files
 
266
      -i IGNORE, --ignore=IGNORE
 
267
                            directories to ignore
 
268
      -w IN_PLACE, --in-place=IN_PLACE
 
269
                            Write .ini files in place; filename to write to
 
270
 
 
271
We only want `.js` files and we want to skip the `restartTests` directory.
 
272
We also want to write a manifest per directory, so I use the `--in-place`
 
273
option to write the manifests:
 
274
 
 
275
    manifestparser create . -i restartTests -p '*.js' -w manifest.ini
 
276
 
 
277
This creates a manifest.ini per directory that we care about with the JS test files:
 
278
 
 
279
    testing/mozmill/tests/firefox/manifest.ini
 
280
    testing/mozmill/tests/firefox/testAwesomeBar/manifest.ini
 
281
    testing/mozmill/tests/firefox/testPreferences/manifest.ini
 
282
    testing/mozmill/tests/firefox/testPrivateBrowsing/manifest.ini
 
283
    testing/mozmill/tests/firefox/testSessionStore/manifest.ini
 
284
    testing/mozmill/tests/firefox/testTechnicalTools/manifest.ini
 
285
    testing/mozmill/tests/firefox/testToolbar/manifest.ini
 
286
 
 
287
The top-level `manifest.ini` merely has `[include:]` references to the sub manifests:
 
288
 
 
289
    [include:testAwesomeBar/manifest.ini]
 
290
    [include:testPreferences/manifest.ini]
 
291
    [include:testPrivateBrowsing/manifest.ini]
 
292
    [include:testSessionStore/manifest.ini]
 
293
    [include:testTechnicalTools/manifest.ini]
 
294
    [include:testToolbar/manifest.ini]
 
295
 
 
296
Each sub-level manifest contains the (`.js`) test files relative to it.
 
297
 
 
298
## Updating the tests from manifests
 
299
 
 
300
You may need to update tests as given in manifests from a different source directory.
 
301
`manifestparser update` was made for just this purpose:
 
302
 
 
303
    Usage: manifestparser [options] update manifest directory -tag1 -tag2 --key1=value1 --key2=value2 ...
 
304
 
 
305
        update the tests as listed in a manifest from a directory
 
306
 
 
307
To update from a directory of tests in `~/mozmill/src/mozmill-tests/firefox/` run:
 
308
 
 
309
    manifestparser update manifest.ini ~/mozmill/src/mozmill-tests/firefox/
 
310
 
 
311
 
 
312
# Tests
 
313
 
 
314
ManifestDestiny includes a suite of tests:
 
315
 
 
316
https://github.com/mozilla/mozbase/tree/master/manifestdestiny/tests
 
317
 
 
318
`test_manifest.txt` is a doctest that may be helpful in figuring out
 
319
how to use the API.  Tests are run via `python test.py`.
 
320
 
 
321
 
 
322
# Bugs
 
323
 
 
324
Please file any bugs or feature requests at
 
325
 
 
326
https://bugzilla.mozilla.org/enter_bug.cgi?product=Testing&component=ManifestParser
 
327
 
 
328
Or contact jhammel @mozilla.org or in #ateam on irc.mozilla.org
 
329
 
 
330
 
 
331
# CLI
 
332
 
 
333
Run `manifestparser help` for usage information.
 
334
 
 
335
To create a manifest from a set of directories:
 
336
 
 
337
    manifestparser [options] create directory <directory> <...> [create-options]
 
338
 
 
339
To output a manifest of tests:
 
340
 
 
341
    manifestparser [options] write manifest <manifest> <...> -tag1 -tag2 --key1=value1 --key2=value2 ...
 
342
 
 
343
To copy tests and manifests from a source:
 
344
 
 
345
    manifestparser [options] copy from_manifest to_manifest -tag1 -tag2 --key1=value1 key2=value2 ...
 
346
 
 
347
To update the tests associated with with a manifest from a source
 
348
directory:
 
349
 
 
350
    manifestparser [options] update manifest from_directory -tag1 -tag2 --key1=value1 --key2=value2 ...
 
351
 
 
352
 
 
353
# Design Considerations
 
354
 
 
355
Contrary to some opinion, manifestparser.py and the associated .ini
 
356
format were not magically plucked from the sky but were descended upon
 
357
through several design considerations.
 
358
 
 
359
* test manifests should be ordered.  While python 2.6 and greater has
 
360
  a ConfigParser that can use an ordered dictionary, it is a
 
361
  requirement that we support python 2.4 for the build + testing
 
362
  environment.  To that end, a `read_ini` function was implemented
 
363
  in manifestparser.py that should be the equivalent of the .ini
 
364
  dialect used by ConfigParser.
 
365
 
 
366
* the manifest format should be easily human readable/writable.  While
 
367
  there was initially some thought of using JSON, there was pushback
 
368
  that JSON was not easily editable.  An ideal manifest format would
 
369
  degenerate to a line-separated list of files.  While .ini format
 
370
  requires an additional `[]` per line, and while there have been
 
371
  complaints about this, hopefully this is good enough.
 
372
 
 
373
* python does not have an in-built YAML parser.  Since it was
 
374
  undesirable for manifestparser.py to have any dependencies, YAML was
 
375
  dismissed as a format.
 
376
 
 
377
* we could have used a proprietary format but decided against it.
 
378
  Everyone knows .ini and there are good tools to deal with it.
 
379
  However, since read_ini is the only function that transforms a
 
380
  manifest to a list of key, value pairs, while the implications for
 
381
  changing the format impacts downstream code, doing so should be
 
382
  programmatically simple.
 
383
 
 
384
* there should be a single file that may easily be
 
385
  transported. Traditionally, test harnesses have lived in
 
386
  mozilla-central. This is less true these days and it is increasingly
 
387
  likely that more tests will not live in mozilla-central going
 
388
  forward.  So `manifestparser.py` should be highly consumable. To
 
389
  this end, it is a single file, as appropriate to mozilla-central,
 
390
  which is also a working python package deployed to PyPI for easy
 
391
  installation.
 
392
 
 
393
 
 
394
# Developing ManifestDestiny
 
395
 
 
396
ManifestDestiny is developed and maintained by Mozilla's
 
397
[Automation and Testing Team](https://wiki.mozilla.org/Auto-tools).
 
398
The project page is located at
 
399
https://wiki.mozilla.org/Auto-tools/Projects/ManifestDestiny .
 
400
 
 
401
 
 
402
# Historical Reference
 
403
 
 
404
Date-ordered list of links about how manifests came to be where they are today::
 
405
 
 
406
* https://wiki.mozilla.org/Auto-tools/Projects/UniversalManifest
 
407
* http://alice.nodelman.net/blog/post/2010/05/
 
408
* http://alice.nodelman.net/blog/post/universal-manifest-for-unit-tests-a-proposal/
 
409
* https://elvis314.wordpress.com/2010/07/05/improving-personal-hygiene-by-adjusting-mochitests/
 
410
* https://elvis314.wordpress.com/2010/07/27/types-of-data-we-care-about-in-a-manifest/
 
411
* https://bugzilla.mozilla.org/show_bug.cgi?id=585106
 
412
* http://elvis314.wordpress.com/2011/05/20/converting-xpcshell-from-listing-directories-to-a-manifest/
 
413
* https://bugzilla.mozilla.org/show_bug.cgi?id=616999
 
414
* https://wiki.mozilla.org/Auto-tools/Projects/ManifestDestiny
 
415
* https://developer.mozilla.org/en/Writing_xpcshell-based_unit_tests#Adding_your_tests_to_the_xpcshell_manifest