tree: 304bb74e1cf6055544ff3fb28d5f6e3da0543dd6 [path history] [tgz]
  1. comment_referable/
  2. end2end/
  3. generator/
  4. mustachio/
  5. render/
  6. src/
  7. templates/
  8. analysis_options.yaml
  9. annotation_test.dart
  10. class_modifiers_test.dart
  11. constant_values_test.dart
  12. container_modifiers_test.dart
  13. dartdoc_options_test.dart
  14. dartdoc_test_base.dart
  15. documentation_comment_test.dart
  16. element_type_test.dart
  17. enum_test.dart
  18. extension_methods_test.dart
  19. extension_types_test.dart
  20. html_generator_test.dart
  21. io_utils_test.dart
  22. library_test.dart
  23. markdown_processor_test.dart
  24. model_node_test.dart
  25. model_utils_test.dart
  26. multiply_defined_test.dart
  27. options_test.dart
  28. package_meta_test.dart
  29. package_test.dart
  30. parameter_test.dart
  32. record_test.dart
  33. resource_loader_test.dart
  34. search_index_test.dart
  35. search_test.dart
  36. source_linker_test.dart
  37. tool_runner_test.dart
  38. typedef_test.dart
  39. utils_test.dart
  40. warnings_test.dart


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:

  1. 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.
  2. “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:

  1. 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">.

  2. 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).

  3. 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.