# Adding Navigation

This document describes what navigation is and how to enhance it.

## Overview

Navigation is the ability to move from one piece of text to a related location.
This includes such things as jumping to the declaration of an identifier or
opening a file based on a URI or file path.

## Enhancing navigation

If we have decided to provide navigation from a given kind of text that was
previously not supported, you can add that support by modifying the class
`_DartNavigationComputerVisitor`. That class is a `RecursiveAstVisitor`, so the
first task is to figure out which kind of node contains the text at the origin.
You can then either add a new `visit` method for the node or edit an existing
method.

If you're adding a new `visit` method, you'll need to invoke the overridden
method to ensure that children are still visited.

Within the `visit` method, compute the region from which the user can navigate
and the location to which they should be navigated. There are some utility
methods in `_DartNavigationCollector`, to make common cases easier, or you can
use `computer.collector.addRegion` to add an arbitrary region.

## Testing the navigation

The tests for navigation are in the class `AnalysisNotificationNavigationTest`.

The tests generally follow the following pattern:

1. Use `addTestFile` to add a file containing both the origin and target of the
   navigation.
2. Use `await prepareNavigation();` to compute and cache navigation results.
3. Use `assertHasRegion` to test that the offset of the string in the test file
   is a navigation origin, and `assertHasTarget` to ensure the target to which
   the user will be navigated.