Maps API Selenium Tests

The svn repository associated with this project contains suites of Selenium tests for the maps api. We know that developers rely on the api to be a stable development platform, and so we have given you the power to create tests which we will run against new versions of the api before they are released. The rest of this document explains how to run the tests and contribute. For now, the repository consists mostly of stubs and incomplete tests, but we hope that will change with your contributions (and as that happens, we look forward to removing this unseemly sentence).

Directory Structure:

The tests are currently broken down into two different folders: "general" and "examples". The "examples" folder specifically contains tests for the pages found at http://code.google.com/apis/maps/documentation/examples/ . The "general" folder contains everything else.

The suites are broken down into three: "stable", "fail", "stub". The "stable" suite contains all tests that reliably pass in all browsers (Safari 2+, FF2+, IE6+) all the time. The "fail" suite contains test that fail either on one or all browsers. The "stub" suite contains tests that are really just stubs - they open a page that we think we should test, but do nothing else. A test should be moved from one suite to the other if it changes state - only the tests in the stable suite will be automatically run before releases.

Within a suite, the corresponding directory contains the test files, and the pages directory inside that contains the js, html, etc. those tests are using.

tests/<suite_name>_stable_suite.html
tests/<suite_name>_todo_suite.html
tests/<suite_name>/<test_name>_test.html
tests/<suite_name>/pages/<test_name>.html (ideally)
tests/<suite_name>/pages/<test_name>.js (ideally)

Selenium extensions are stored in core/scripts/extensions, though a call needs to be added to user-extensions.js to add them.

core/scripts/user-extensions.js
core/scripts/extensions/<extension_name>.js

If you want to do a comprehensive reorganization of the tests, feel free to experiment, and if we think it makes sense, we'll accept the change. We know that the current test structure could be improved.

Running Tests:

To run a test suite in your browser, simply go to:

<selenium_directory>/core/TestRunner.html?test=../tests/<suite_name>_suite.html

You can use a local file directory (if you have checked out the project), or you can run the tests directly from the svn repository with

<selenium_directory>

You can also run tests on different versions of the api by appending various arguments to the suite url. See http://gmaps-api-issues.googlecode.com/svn/trunk/selenium/tests/README.html for more information.

New Tests:

Make sure to follow conventions when adding tests, both of coding style and directory structure. The conventions we use can be found here: http://code.google.com/p/gmaps-utility-library-dev/wiki/JavascriptCodingConventions. Also, when adding files, make sure to svn propset the files to their corresponding mime types so that they load correctly in the repository. The most common example of that is for HTML files:

find . -name '*.html' | xargs svn propset svn:mime-type text/html

Contributing:

We welcome external developers to add tests to this project. Please do the following:

1. Do an anonymous checkout of this project.
2. Add the two HTML files needed to define and run a test, and any helper functions necessary to user-extensions.js.
3. Add the test to one of the suites.
4. Run the tests in as many browsers and operating systems as you have access to. We'll only be able to accept tests that pass in all browser/OS combinations (OS/Windows/Linux with FF1.5+/IE6+/Safari2+).
5. Run svn diff on your copy of the repository.
6. Create an issue on the Issue Tracker and indicate that it's a patch with a test.
7. Your issue will be reviewed and you'll be notified of any outstanding issues with the test or if it's been integrated into the trunk.

In the future, we may add developers directly to the project that have consistently created good tests. For now, we will accept them as patches.