Getting Started Testing Dartdoc Fixes

‹prev | My Chain | next›

Last night I was able to find and fix a minor bug in the dartdoc documentation tool for Dart libraries. Tonight, I would like to do what I can to get that fix back into the Dart SDK.

Before starting with the code review process that the Dart project uses, I would like to perform some preliminary testing investigation. First, I would like to see if my change breaks any tests. If not, I would like to add one so that this situation does not arise again.

In the Dart SDK mirror that I have copied from GitHub, I find dartdoc tests in dart/sdk/lib/_internal/dartdoc/test. These tests use the new import and library syntax, so the dart installed on my system will not work (it still expects #import and #library). Instead, I use the dart executable bundled in the SDK, which is located at dart/tools/testing/bin/linux/dart.

Even that does not work, however. When I try to run one of the dartdoc tests, I get an error about the unittest path:

➜  dart-sdk git:(master) ./dart/tools/testing/bin/linux/dart ./dart/sdk/lib/_internal/dartdoc/test/dartdoc_test.dart
Unable to open file: /home/chris/repos/dart-sdk/dart/sdk/lib/pkg/unittest/lib/unittest.dart'
file:///home/chris/repos/dart-sdk/dart/sdk/lib/_internal/dartdoc/test/dartdoc_test.dart': Error: line 13 pos 1: library handler failed
import '../../../pkg/unittest/lib/unittest.dart';
^

In the problem file, I find a note about the path used to include unittest.dart:

// TODO(rnystrom): Better path to unittest.
import '../../../pkg/unittest/lib/unittest.dart';

The bundled SDK uses different paths for these tools and libraries. Perhaps the build paths are used here. That or there is a build process that I am bypassing while attempting to run my tests directly. I will worry about that another day. For now, I modify the import statement, adding a few more parent directory references:

// TODO(rnystrom): Better path to unittest.
import '../../../../../pkg/unittest/lib/unittest.dart';

With that, I am able to run the test:

➜  dart-sdk git:(master) ✗ ./dart/tools/testing/bin/linux/dart ./dart/sdk/lib/_internal/dartdoc/test/dartdoc_test.dart
unittest-suite-wait-for-done
PASS: countOccurrences empty text returns 0
PASS: countOccurrences one occurrence
PASS: countOccurrences multiple occurrences
PASS: countOccurrences overlapping matches do not count
...
All 19 tests passed.
unittest-suite-success

After making similar changes in other dartdoc test files, I find that all tests pass. Furthermore, it seems that there are no obvious test files that cover the problem area, which is the CommentMap.

I get started on creating one, but fail to make much progress on writing a failing test case. This seems to be a fairly full-stack test requiring a Location object. I tend to doubt that I am going to get this test right, but I'll be darned if I submit a patch without a test. Hopefully, I can get that finished tomorrow.

Day #560