These instructions will guide you through the Observatory development and testing workflow.
Getting ready to start.
Before you start to hack on Observatory, follow the instructions to have a working environment in which you are able to build and test the Dart SDK.
Before hacking Observatory let's run the existing Observatory tests. We suggest to run all the test in debug mode.
First build the sdk in debug mode
$ ./tools/build.py --mode debug create_sdk
From the root of the sdk repository run:
$ ./tools/test.py -mdebug service
Observatory is built as part of building the sdk. Previously, it was recommended to run the Observatory using pub serve
to avoid having to rebuild the sdk for each change to Observatory. However, pub serve
was deprecated as part of the transition to Dart 2.0.
Issue #35678 tracks changes required to allow for package:build_runner
to run Observatory without having to rebuild the sdk after each change.
Start a Dart VM with the --observe
flag (as explained in the get started guide) and connect your Observatory instance to that VM.
Example script (file name clock.dart
):
import 'dart:async' show Timer, Duration; main() { bool tick = true; new Timer.periodic(const Duration(seconds: 1), (Timer t) { print(tick ? 'tick' : 'tock'); tick = !tick; }); }
Start the script:
$ dart --disable-service-origin-check --observe clock.dart
The development workflow of Dart (and Observatory) is based on code reviews.
Follow the code review instructions to be able to successfully submit your code.
The main reviewers for Observatory related CLs are:
All the service tests are located in the tests/service
folder. Test file names follow the convention <description>_test.dart
(e.g. a_brief_description_test.dart
).
The test is generally structured in the following way.
import 'package:test/test.dart'; main() { // Some code that you need to test. var a = 1 + 2; // Some assertions to check the results. expect(a, equal(3)); }
See the official test library instructions;
The test_helper.dart
file expose some functions that allow to run a part of the code into another VM.
To test synchronous operations:
import 'test_helper.dart'; code() { // Write the code you want to be execute into another VM. } var tests = [ // A series of tests that you want to run against the above code. (Isolate isolate) async { await isolate.reload(); // Use the isolate to communicate to the VM. } ]; main(args) => runIsolateTestsSynchronous(args, tests, testeeConcurrent: code);
In order to test asynchronous operations:
import 'test_helper.dart'; code() async { // Write the asynchronous code you want to be execute into another VM. } var tests = [ // A series of tests that you want to run against the above code. (Isolate isolate) async { await isolate.reload(); // Use the isolate to communicate to the VM. } ]; main(args) async => runIsolateTests(args, tests, testeeConcurrent: code);
Both runIsolateTests
and runIsolateTestsSynchronous
have the following named parameters:
Some common and reusable test are available from service_test_common.dart
:
See: Run existing tests