Testing changes before upload

Before you upload a changeset, you may wish to test it in one or more applications that use OpenStreetMap data to ensure that your changes have the effect you intended. Many OpenStreetMap-based applications have ways that you can load custom data for this purpose, though the procedures vary widely in difficulty. There's no general expectation that contributors do such testing. But testing your own change while you have it fresh in your mind can sometimes be the most efficient way to detect and fix any problems, compared to uploading, waiting for the main instances of OpenStreetMap-based applications to update their map data to include your changeset, and then testing your changes there (or leaving any problems for other contributors to notice and investigate later). This can be especially useful for certain kinds of changes, such as changes to routing restrictions, where you may want to query several example routes to ensure that your restriction only affected the intended routes.

In general, the testing process works like this:

1. First, you need to have access to an instance of the application in which you have the ability to load custom data. For an application designed to run on your own computer or phone (such as OsmAnd), this may be as easy as installing the application the normal way, whereas for a web-based application (such as OSRM), the process to install your own instance is often not very user-friendly. (Providing shared instances of popular web-based applications that allow contributors to load custom data for testing would be an interesting future possibility for the community.)
2. Then, you load your data. Typically, you have your editor save a JOSM file of a small region that includes your change. Then you convert the JOSM file to an application-specific format by a process similar to the one used by the main instance of the application on the official map, but just on your small custom file, so the computing resources required will typically be much lower than what the documentation suggests for large regions of the map.

Gotcha: Applications designed to consume OSM files that represent a published map may have issues consuming JOSM files that represent a pending change. In particular, elements pending deletion are included in the JOSM file with the action='delete' attribute. Consuming applications (e.g., OsmAndMapCreator) may not be aware of this attribute and may show those elements on the map as if you had not deleted them. It's not obvious what is conceptually the best solution to issues of this nature. But a quick fix for the action='delete' problem is to make a copy of your JOSM file with the deleted objects removed and load that into the other application. This is straightforward to do with XSLT; please update this wiki page if you know a better solution using standard OSM tools. Assuming your system has xsltproc, you can download osm-file-strip-deleted.xsl and then run xsltproc osm-file-strip-deleted.xsl my-pending-change.osm >my-pending-change.stripped.osm.

Tip: If your data is not working as expected in the application, sometimes the cause may be obvious and sometimes it may require a long investigation. To avoid wasting time, first run your editor's validator to catch any common problems. At some point, you may decide that the possible benefit of catching an error in your change does not justify the cost of continued research; that's fine.

The rest of this page has some details about testing changes in particular applications.

OsmAnd

OsmAnd is one of the best applications for testing changes because loading custom data is relatively easy and the set of things you can test is relatively complete (notably, routing). Use OsmAndMapCreator to convert the OSM file to OsmAnd's OBF format and follow the instructions to install your OBF file on your phone. When you're done testing, just delete your OBF file and reactivate the official map of the region. Alternatively, if your phone provides a way to install multiple instances of the same application (e.g., a work profile or private space on Android), you can set up one instance of OsmAnd with the official maps and one with your own OBF file for easy comparison.

If your data doesn't appear as expected in OsmAnd, the problem could be due to your data or to a difference between your OBF generation process and the official one. A helpful technique is to find an existing feature on OSM that is similar to the one you're editing and load it into your OSM file. Then you can compare how that feature appears on the official OBF and the OBF you generated. If the same problem occurs, then the problem is with the OBF generation. Here are some anecdotal reports of problems and solutions (not verified to work in all cases but worth a try if you have the same symptom):

• When selecting a POI with an address, the address did not appear in the pop-up panel. Adding the city node to the OSM file fixed the problem. In this case, the "generation process difference" was that the official OBF covered a large area that included the city node, whereas the custom OBF initially included only the area being edited.

One feature that would be useful for testing that OsmAnd doesn't have as of this writing is the ability to set a custom time to evaluate conditional restrictions (unless you're willing to change your phone's system clock or use an emulator, etc.).