Added HACKING.md to observatory

runtime/observatory/HACKING.md

+# Hacking Observatory
+
+These instructions will guide you through the Observatory development and testing workflow.

[Cutch, 2016/06/20 14:06:12]

(here and elsewhere) lines must be <= 80 columns long

[cbernaschina, 2016/06/20 14:33:47]

Done.

+
+## SDK Setup & Build
+Getting ready to start.
+
+Before starting hacking observatory follow [the instructions][1] to have a working environment in which you are able to build and test the Dart SDK.
+
+## Run existing tests
+Before hacking Observatory let's run the existing Observatory tests.
+
+From the root of the sdk repository run:
+```
+$ ./tools/test.py -mrelease service
+```
+
+## Develop with Dartium ~ Suggested
+If you want to avoid to trigger a new compilation to JavaScript for each edit you do, you can use a modified version of Chromium named Dartium that will interpret you dart code directly.
+
+You can obtain Dartium in two different ways:
+1. [Download the binaries][2]
+2. [Build Dartium from the source code][3]
+
+## Serve Observatory
+In order to avoid a complete build of the sdk for each change you do to Observatory, we are going to __serve__ it directly.
+
+Use __pub__ to __serve__ Observatory:
+```
+[...]/runtime/observatory$ pub serve
+```
+
+## Open Observatory
+You can open the development version of Observatory from Chrome/Chromium/__Dartium__ by navigating to [localhost:8080][4]
+
+Every change you make to the Observatory source code will be visible by simply __refreshing__ the page in the browser.
+
+## Connect to a VM
+Start a Dart VM with the ``--observe`` flag (as explained in the [get started guide][5]) and connect your Observatory instance to that VM.
+
+## Code Reviews
+The development workflow of Dart (and Observatory) is based on code reviews.
+
+Follow the [code review instructions][6] to be able to successfully submit your code.
+
+The main reviewers for Observatory related CLs are:
+  - turnidge
+  - johnmccutchan
+  - rmacnak
+
+## Write a new service test
+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.
+```dart
+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][7] 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:
+```dart
+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:
+```dart
+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:
+ - __testeeBefore__ (void()) a function that is going to be executed before the test
+ - __testeeConcurrent__ (void()) test that is going to be executed
+ - __pause_on_start__ (bool, default: false) pause the Isolate before the first instruction
+ - __pause_on_exit__ (bool, default: false) pause the Isolate after the last instruction
+ - __pause_on_unhandled_exceptions__ (bool, default: false) pause the Isolate at an unhandled exception
+ - __trace_service__ (bool, default: false) trace VM service requests
+ - __trace_compiler__ (bool, default: false) trace compiler operations
+ - __verbose_vm__ (bool, default: false) verbose logging
+
+
+Some common and reusable test are available from ```service_test_common.dart```:
+ - hasPausedFor
+   - hasStoppedAtBreakpoint
+   - hasStoppedWithUnhandledException
+   - hasStoppedAtExit
+   - hasPausedAtStart
+ - stoppedAtLine
+
+and utility functions:
+ - subscribeToStream
+ - cancelStreamSubscription
+ - asyncStepOver
+ - setBreakpointAtLine
+ - resumeIsolate
+ - resumeAndAwaitEvent
+ - resumeIsolateAndAwaitEvent
+ - stepOver
+ - getClassFromRootLib
+ - rootLibraryFieldValue
+
+## Run your tests
+See: __Run existing tests__
+
+[1]: https://github.com/dart-lang/sdk/wiki/Building           "Building the Dart SDK"
+[2]: https://www.dartlang.org/tools/dartium/                  "Download Dartium"
+[3]: https://github.com/dart-lang/sdk/wiki/Building-Dartium   "Build Dartium"
+[4]: http://localhost:8080/                                   "Open Observatory"
+[5]: https://dart-lang.github.io/observatory/get-started.html "Observatory get started"
+[6]: https://github.com/dart-lang/sdk/wiki/Code-review-workflow-with-GitHub-and-reitveld "Code Review"
+[7]: https://pub.dartlang.org/packages/test                    "Test Library"