← Back to branch summary

~canonical-platform-qa/autopilot/fix-bug-1414781

« back to all changes in this revision

Viewing changes to docs/guides/running_ap.rst

  • Committer: Tarmac
  • Author(s): Christopher Lee
  • Date: 2015-01-22 22:03:13 UTC
  • mfrom: (527.1.7 docs-running-tests)
  • Revision ID: tarmac-20150122220313-jbnjzpg0u01da0vv
Adding details to README re: running/listing autopilot tests.

Approved by PS Jenkins bot, Thomi Richards.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/guides/running_ap.rst
8
8
 
9
9
Autopilot can list all tests found within a particular module::
10
10
 
11
 
    $ autopilot list <modulename>
 
11
    $ autopilot3 list <modulename>
12
12
 
13
13
where *<modulename>* is the base name of the module you want to look at. The module must either be in the current working directory, or be importable by python. For example, to list the tests inside autopilot itself, you can run::
14
14
 
15
 
     $ autopilot list autopilot
 
15
     $ autopilot3 list autopilot
16
16
        autopilot.tests.test_ap_apps.GtkTests.test_can_launch_qt_app
17
17
        autopilot.tests.test_ap_apps.QtTests.test_can_launch_qt_app
18
18
        autopilot.tests.test_application_mixin.ApplicationSupportTests.test_can_create
39
39
 
40
40
Running autopilot tests is very similar to listing tests::
41
41
 
42
 
    $ autopilot run <modulename>
 
42
    $ autopilot3 run <modulename>
43
43
 
44
44
However, the run command has many more options to customize the run behavior:
45
45
 
70
70
 
71
71
1. **Run autopilot and save the test log**::
72
72
 
73
 
    $ autopilot run -o . <modulename>
 
73
    $ autopilot3 run -o . <modulename>
74
74
 
75
75
  Autopilot will create a text log file named <hostname>_<dd.mm.yyy_HHMMSS>.log with the contents of the test log.
76
76
 
77
77
2. **Run autopilot and record failing tests**::
78
78
 
79
 
    $ autopilot run -r --rd . <modulename>
 
79
    $ autopilot3 run -r --rd . <modulename>
80
80
 
81
81
  Videos are recorded as *ogg-vorbis* files, with an .ogv extension. They will be named with the test id that failed. All videos will be placed in the directory specified by the ``-rd`` option - in this case the currect directory. If this option is omitted, videos will be placed in ``/tmp/autopilot/``.
82
82
 
83
83
3. **Save the test log as jUnitXml format**::
84
84
 
85
 
    $ autopilot run -o results.xml -f xml <modulename>
 
85
    $ autopilot3 run -o results.xml -f xml <modulename>
86
86
 
87
87
  The file 'results.xml' will be created when all the tests have completed, and will be in the jUnitXml file format. This is useful when running the autopilot tests within a jenkins environment.
88
88
 
94
94
In order to be able to introspect an application, it must first be launched with introspection enabled. Autopilot provides the **launch** command to enable this: ::
95
95
 
96
96
    $ autopilot3 launch <application> <app_parameters>
97
 
    
 
97
 
98
98
The *<application>* parameter could be the full path to the application, or the name of an application located somewhere on ``$PATH``. *<app_parameter>* is passed on to the application being launched.
99
99
 
100
100
A simple Gtk example to launch gedit::
101
101
 
102
102
    $ autopilot3 launch gedit
103
103
 
104
 
A Qt example which passes on parameters to the application being launched:: 
 
104
A Qt example which passes on parameters to the application being launched::
105
105
 
106
106
    $ autopilot3 launch qmlscene my_app.qml
107
107
 
108
 
Autopilot launch attempts to detect if you are launching either a Gtk or Qt application so that it can enable the correct libraries. If it is unable to determine this you will need to specify the type of application it is by using the -i argument. This allows "Gtk" or "Qt" frameworks to be specified when launching the application. The default value ("Auto") will try to detect which interface to load automatically. 
 
108
Autopilot launch attempts to detect if you are launching either a Gtk or Qt application so that it can enable the correct libraries. If it is unable to determine this you will need to specify the type of application it is by using the -i argument. This allows "Gtk" or "Qt" frameworks to be specified when launching the application. The default value ("Auto") will try to detect which interface to load automatically.
109
109
 
110
110
A typical error in this situation will be "Error: Could not determine introspection type to use for application". In which case the -i option should be specified with the correct application framework type to fix the problem::
111
111