Tests

Many of dartdoc's tests are large end-to-end tests which read real files in real packages, in the testing/ directory. These tests are found in test/end2end/. Smaller unit tests are found in test/ and other subdirectories.

Many of the end-to-end test cases are being rewritten as unit tests. Eventually, the content in the testing/ directory should dwindle down to very targeted tests which cannot be rewritten as unit tests.

There are some end-to-end tests which would require a serious refactoring of the implementation in order to migrate to unit tests, such as any “tool” test (testing the {@tool} directive).

Manual testing

We have not set up programmatic tests for the behavior of the front-end. Two areas of complexity which should be tested for any front-end change are:

Search - this includes the search box at the top right of the desktop view, the search box in the mobile view, and the search results in the search.html page.
“Base href” - This is complicated. But documentation for some code makes use of the base HTML element, and some does not, as determined by the data-using-base-href attribute on the body tag. Some URLs are constructed using this attribute, so manual testing must include a case where it is used, and a case where it is not.

For the “base-href” behavior, you can manually test with the following grinder commands:

dart run grinder serve-test-package-doc - This serves the docs for the testing/test_package package at http://localhost:8002/. The “base href” settings result in a body tag like: <body data-base-href data-using-base-href="false">.
dart run grinder serve-pub-package - This serves the docs for a pub package at http://localhost:9000/. Environment variables are used to pass the package name and version. For example: PACKAGE_NAME=collection PACKAGE_VERSION=1.17.0 dart run grinder serve-pub-package. The “base href” settings result in a body tag like: <body data-base-href="./" data-using-base-href="false">. Serving up a package's docs gives the opportunity for many search results.
The trick here is to test on different pages, which should change that data-base-href attribute to different values. I think typically the value is "../" on a library page or library member page, and "../../" on a library member's member page (like a constructor of a class).
flutter pub run grinder serve-flutter-docs (warning: takes a crazy long time)
- This serves the docs for Flutter at http://localhost:8001/. The “base href” settings result in a body tag like: <body data-base-href data-using-base-href="true"> and a base tag in the head like <base href="./flutter/">.
TODO(srawlins): Yikes that flutter step is too expensive. Figure out a simple grinder task for using “base href” with a simple package.