rangle / augury

Angular Debugging and Visualization Tools

Angular DevTools

With the release of Angular DevTools, Augury is not being maintained. Please download Angular DevTools from Chrome Web Store and use rangle/angular-devtools repo to log any issues.

Read More about the release:

• Introducing Angular DevTools
• Introducing the New Angular DevTools

Augury

Check out the Augury Labs project for new experimental Angular developer tools.

Table of content

1. Introduction
2. Supported version
3. Working on Augury
4. Building and installing locally
5. Running tests
6. Reporting issues
7. Contributing
8. Known issues

Introduction

Augury is a Chrome & Firefox Developer Tools extension for debugging Angular 2+ applications.

You can install the extension from:

• Chrome Store
• Firefox Add-ons

You may also install our Canary Build for Chrome to try out new features and bug fixes, and help us with user acceptance testing.

Inspecting Code

Augury only works with Angular 2+ applications. A hard requirement is that the Angular application is running in development mode, this is due to a security restriction. If you plan to read the original source code, it is a good idea to generate source maps. Otherwise you will be forced to work with the compiled JavaScript code.

Supported version

Augury works with application built starting with Angular 2+. Augury currently does not have support for Angular Ivy as of Augury v1.

---

Working on Augury

Development environment

To develop the Augury extension, the following environment is used:

• Node
• NPM
• TypeScript

Building and installing locally

To install Augury locally, perform the following steps:

git clone git://github.com/rangle/augury
cd augury
npm install
npm run build:dev

Try out the extension with one of the example app from the Guide.

Chrome

1. Navigate to chrome://extensions and enable Developer mode.
2. Choose "Load unpacked extension".
3. In the dialog, open the directory you just cloned.

Firefox

1. Navigate to about:debugging#addons to load add-on.
2. Click Load Temporary Add-on
3. In the dialog, open the directory you just cloned, and select the manifest.json file.

Running tests

Automated testing

To execute all unit tests, run npm test. It bundles up all files that match *.test.ts into build/test.js, then runs it through tape-run in a headless Electron browser.

Manual Testing

If you currently have the Augury extension installed from the Chrome Web Store or Firefox Add-ons, you can manually test your change by switching between your local dev production and production version of Augury in the extension window of your browser. Only one version of the tool should be active at a time.

Available NPM scripts

To see all available script type npm run in the terminal. The following command are the ones you will mostly be working with.

Command	Description
start	Clean build and run webpack in watch mode
webpack	Runs webpack in watch mode
build	Builds the extension
clean	Clean the build directory,
test	Bundle all *.test.ts and run it through a headless browser
lint	Run tslint on all source code
pack	Packages the extension for browser specific builds

Reporting issues

Please search to make sure your issue is not already been reported.

You should report an issue directly from Augury, by clicking on the Augury icon next to the address bar in the browser. It will open up a popup menu with a link to Issue reporting.

Contributing

General guidelines

If you'd like to help out, please read our Contributing Guidelines.

Augury Architecture

You might want to first checkout the Architecture of this extension.

Join on Slack

If you want to contribute or need help getting started, join us on Slack.

---

Known issues

Router graph

The router injection technique described below applies to version before those listed below:

Angular v2.3.0
Angular Router v3.3.0
Augury v1.2.8

To be able to view the router graph, you will need to inject the Router in the application Root component as shown below (it must be named router exactly).

export default class KitchenSink {
  constructor(private router: Router) {
  }
}

Example code

Support for AoT (Ahead-Of-Time) compilation

In order for Angular to expose the debug information for AoT applications, you will have to explicitly set the debug flag to true in your project's tsconfig.json as such:

"angularCompilerOptions": {
  /* ... */
  "debug": true
}

Note: This debug flag and development mode in Angular runtime are two completely different settings.

To learn more about AoT compilation, visit this section of Angular documentation.

Support for enableDebugTools()

Prior to Angular 2.2.0, enableDebugTools() would clobber ng.probe, which breaks Augury. Prior to that version, this workaround will circumvent the issue.

No state for some components

The date polyfill core-js/es6/date can throw an exception when stringifying a component. To workaround this issue, exclude this polyfill in your development environment.

License

MIT

augury's Issues

Add a code of conduct

Objective: Foster an inclusive environment and lower the barrier to entry in participating to the project.

Concerns

• Some past attempts at this have either been derailed by "controversy" or been drowned in equivocations. Needless to say, we should probably avoid this. 😏
• We MUST have a contact email address.
• It'd be great if the community could be empowered to self-police (i.e. little to no formal moderation).

Prior art

• MINASWAN
  • More of a motto than a COD, per se, but likely the most effective thing I've ever seen.
• The Rust Code of Conduct
  • Simple, clear and concise
  • Amazing work by the Rust team
• Citizen Code of Conduct
  • A strong template, great definitions
• Node.js's Inclusivity Working Group
  • Early days but it's definitely a novel approach (there have been similar attempts but not quite like this, it seems)
  • We have no need for this level of formalism but their focus on specificity and actionability is worth paying attention to (see: nodejs/inclusivity#22)

Fix Example Application

Another thing that needs to get done is to fix the example application.
I believe that currently adding, deleting or editing tasks does not work, this needs to be fixed

Fix compiler errors on the example-app

Currently the tsc command produces 2 compile time errors related to the Angular 2.0 debug classes that we are importing.

build error with duplicate identifier Promise

When I use gulp build there's Duplicate identifier 'Promise' error in es6-promise.d.ts and es6-shim.d.ts files. And I checked the target is ES5 in tsconfig. Is there anything I can do to resolve this error? And my dev box is Windows 10. Thanks!

Be able to see a count of all available scopes/components in play at a given time

Being able to see a count of all the different components being used at a given time would be awesome. So example: 1 root-component, 1 header-component, 1 body-component, 5 collapsible-component, 2 item-component, 1 footer-component, etc.

This would be good for seeing what components are used the most for performance sake and if there's and fishy business happening in larger applications.

@igor-ka as we talked about

Setup test infrastructure

Objective: Allow local tests and enable CI integration for each PR and merge.

Concerns

• Integrate juliangruber/tape-run or some other TAP-producing test framework
  • It MUST report the right 0/1 status code when running within a browser (headless or otherwise)
• We need some "sample" passing tests
• We can probably get away with testing on the Chrome Browser present in CircleCI, for now...

As a user I want to look for elements so that I can quickly see what I am trying to find (Search Input)

• Redesign the search input component

Cleanup the example app and the repo

This repository was made by copying the code from the batarangle repo (not a fork).
We need to cleanup the example application in the new repo.

• cleanup typings
• cleanup .gitignore for main repo and example app
• remove build artifacts from the repo

message: "ng is not defined"

I am trying to use batarangle with this repo:

https://github.com/robianmcd/ng2-movies

But having above message in the components panel. Also, nothing shows in angular 2 panel in developers tools.

Performance view prototype

Feature goal: The user should be able to assess the impact of change detection on each component at-a-glance.

@abmohan – we're probably looking to prototype the best way of doing this.

/cc @winkerVSbecks

Cannot resolve module rxjs/*

As of this commit in alpha-48, Angular is importing RxJS modules via rxjs rather than @reactive/rxjs. #45 did not update Batarangle's dependencies accordingly, resulting in this warning on npm install:

[email protected] requires a peer of [email protected] but none was installed.

npm run build then barfs on Cannot resolve module rxjs/* for all rxjs modules, and the resultant extension is nonfunctional.

Changing the import in package.json and updating the import statements in /backend/base, /frontend/dispatcher/dispatcher and /stores/abstract-store seems to resolve the problem and results in a successful build, with all tests still passing. Submitting PR with these changes now.

Error: Cannot read property 'properties' of undefined

I'm trying to run batarangle on my Angular2 app (found here https://github.com/robianmcd/tag-trends) but I get the following output in the console and none of my components are shown in the batarangle frontend

Backend: Message Received: Object {name: "init", tabId: 39} Object {id: "cppbdcpcfamjjmdinkfmddacbdgpdboa"}
Backend: Message Received: Object {name: "message", tabId: 39, message: Object}message: ObjectactionType: "START_COMPONENT_TREE_INSPECTION"__proto__: Objectname: "message"tabId: 39__proto__: Object 

Uncaught TypeError: Cannot read property 'properties' of undefined
    Angular2Adapter._getComponentProperties @   angular2.ts:273

I modified my bootstrap file to look like this

import {bootstrap} from 'angular2/platform/browser';
import {bind} from 'angular2/angular2';
import {AppViewListener} from 'angular2/src/core/linker/view_listener';
import {DebugElementViewListener, inspectNativeElement} from 'angular2/src/platform/dom/debug/debug_element_view_listener';
import {App} from "./components/app/app";
import {UrlUtil} from './services/urlUtil';

bootstrap(App, [
    bind(AppViewListener).toClass(DebugElementViewListener)
]).then(applicationReference => {
    window['ng']['probe'] = inspectNativeElement;
});

I'm running Alpha 48 so maybe this is happening because of the mismatched angular versions. I can run batarangle with the example app just fine. Any idea?

Implement a simple "Component Inspector"

We want to be able to click a magnifying glass within Chrome Dev Tools and get back some information about the component.

Cannot install with current instructions

Using the current instructions installation fails.
I had to do the following manually.. and then after running the example todo app I'm unable to use batarangle.

1201  [2015-11-01 04:36:19] git clone git://github.com/rangle/batarangle
1204  [2015-11-01 04:43:58] npm build
...
1213  [2015-11-01 04:45:25] npm i tappable
1214  [2015-11-01 04:45:33] npm i webpack
1218  [2015-11-01 04:47:27] npm i minimatch
1220  [2015-11-01 04:47:52] npm i inherits
1223  [2015-11-01 04:48:23] npm i inflight
1224  [2015-11-01 04:48:30] npm run webpack
1235  [2015-11-01 04:52:43] npm i rimraf -g
1236  [2015-11-01 04:53:07] npm run clean
1238  [2015-11-01 04:53:33] npm run remove-tsd-loader-typings
1239  [2015-11-01 04:53:47] npm run tsd-update
1244  [2015-11-01 04:55:18] npm i object-assign

Now installing the extension works.

When running the todo app I had to:
(after running npm install)..
1245 [2015-11-01 04:55:23] npm run start
1254 [2015-11-01 04:57:25] npm i jspm -g

I get the following errors:

bootstrap e9b1a9dfad7ad8fdc39a?cbc5**:39 Uncaught Error: Cannot find module "./backend/batarangle-backend"webpackMissingModule @ bootstrap e9b1a9dfad7ad8fdc39a?cbc5**:39(anonymous function) @ bootstrap e9b1a9dfad7ad8fdc39a?cbc5**:39__webpack_require__ @ bootstrap e9b1a9dfad7ad8fdc39a?cbc5**:19(anonymous function) @ bootstrap e9b1a9dfad7ad8fdc39a?cbc5**:39(anonymous function) @ bootstrap e9b1a9dfad7ad8fdc39a?cbc5**:39
2015-11-01 05:10:04.754 system.js:4 GET http://127.0.0.1:3001/APPSOA/Components/DashboardComponent.ts 404 (Not Found)L @ system.js:4(anonymous function) @ system.js:4lib$es6$promise$$internal$$initializePromise @ angular2.dev.js:1554lib$es6$promise$promise$$Promise @ angular2.dev.js:1845(anonymous function) @ system.js:4(anonymous function) @ system.js:4(anonymous function) @ system.js:4(anonymous function) @ system.js:5(anonymous function) @ system.js:5(anonymous function) @ system.js:5(anonymous function) @ system.js:5(anonymous function) @ system.js:5(anonymous function) @ system.js:4run @ angular2.dev.js:138zoneBoundFn @ angular2.dev.js:111lib$es6$promise$$internal$$tryCatch @ angular2.dev.js:1507lib$es6$promise$$internal$$invokeCallback @ angular2.dev.js:1519lib$es6$promise$$internal$$publish @ angular2.dev.js:1490(anonymous function) @ angular2.dev.js:219run @ angular2.dev.js:138zoneBoundFn @ angular2.dev.js:111lib$es6$promise$asap$$flush @ angular2.dev.js:1301

Reference to AppViewListener is wrong [Alpha 46]

Inside the example app you include the AppViewListener this way:

import {AppViewListener} from 'angular2/src/core/linker/view_listener.js';

This results in Cannot find module angular2/src/core/linker/view_listener.js for me.

More condensed nested component view

The view on the left that shows all the components as gray blocks nested within each other feels too large and spread out. With deep complex hierarchies or long repeated lists it's going to be tiresome scrolling around the list while keeping a sense of where you are within the list.

Have you considered any other layouts?

• HTML tags, similar to react dev tools
• collapsable shorter blocks, similar to Mac OS Finder List view

Batarangle error with angular 2 beta 0

Using the code to connect Batarangle to the Angular 2 app from the README generates an error in the console with Angular2 beta 0:

import { AppViewListener } from 'angular2/src/core/linker/view_listener';
import { DebugElementViewListener } from 'angular2/platform/common_dom';
import { bind } from 'angular2/core';

bootstrap(AppComponent, [
  bind(AppViewListener).toClass(DebugElementViewListener)
]);

As soon as the Angular2 tab in devtools is opened for the first time, we get this:

Uncaught TypeError: nativeElement.setAttribute is not a function
Angular2Adapter._emitNativeElement 
@ angular2.ts:133Angular2Adapter._traverseTree 
@ angular2.ts:109(anonymous function) 
@ angular2.ts:122forEach 
@ es6-shim.js:1107Angular2Adapter._traverseTree 
@ angular2.ts:121(anonymous function) 
@ angular2.ts:57forEach 
@ es6-shim.js:1107Angular2Adapter.setup 
@ angular2.ts:56(anonymous function) 
@ entry.ts:19__webpack_require__ 
@ bootstrap 11a0ead175d757e7a340?343e:19(anonymous function) 
@ bootstrap 11a0ead175d757e7a340?343e:39__webpack_require__ 
@ bootstrap 11a0ead175d757e7a340?343e:19(anonymous function) 
@ bootstrap 11a0ead175d757e7a340?343e:39(anonymous function) 
@ bootstrap 11a0ead175d757e7a340?343e:39

Subsequent DOM updates don't seem to be handled by the Batarangle front end.

As a user I want to see what element I am viewing for so that I can know where in the application I am (Element highlight on tree structure and properties tab element label)

Compile error due from typings

Need to install all the typings dependencies from tsd install as opposed to some being linked from the node_modules folder using tsd link. This way the typings can reference each other from a common location.

For example angular2 comes with a typings for es6-promise with angular2 referencing it. Also chrome typings installed from tsd repo have es6-promise as a dependency, typings for which get installed into /typings folder.

During compilation both the es6-promise from node_modules/angular2 and es6-promise from typings folder (referenced by chrome.d.ts) are present on the build path, causing a compile time error of duplicate occurrence of symbol.

Refactor search

Search seems to be breaking/just not working at all in some cases.

State normalization for directives

NgFor & NgIf first; other directives to be followed.

Rework script injection and messaging workflow

Currently the our "backend" script gets injected on the onload event of the inspected apps document.
This results in a situation where if the dev tools page was closed and re-open a refresh button has to be pressed in order to get the script injected again.

Need to investigate and provide a better workflow in terms of script injection. React Dev Tools source code will probably have an answer to this problem.

Research a way to get to the root component

This could probably be achieved for now, is by passing a ComponentRef returned by bootstrap into inspectNativeElement provided by Angular 2.0

Gather Ideas for Features

1. We need to evaluate existing tools inspiration on features for

• React Dev Tools
• ng-inspector

2. Also, we need to potentially think of original ideas to as to what else could be useful for Angular 2 Dev tools. (This might end up a bigger scale, soul searching task that potentially could involve other devs at Rangle and maybe elsewhere/Google?)

3. Finally we need more investigation on what kind of hooks Angular 2 exposes to us. Gladly we have a slack channel to ask them.

Switch to webpack and NPM for dependency management and build

Clean up the data shown on Component Inspector Pane

Currently the data shown on the component inspector pane is disorganized.
Need to give the data shown proper labels and decide what is most useful to show.

Investigate better way to deal with data clone error

As per @igor-ka's suggestion in #55

As a user I want to see all the elements on my application so that I can view an overview of the full application structure (Tree Structure)

Show typescript sources in chrome devtools stacktrace

If I include sourcemaps in an app, I can open the original typescript source file and set breakpoints.
However, stacktraces still reference the .js file so clicking through those links takes me to the wrong place.
Probably a chrome issue but it seems like you guys could drive the fix?

Add TS linting

This looks promising to use with webpack: https://www.npmjs.com/package/tslint-loader

Dynamically loaded components do not get displayed

Components loaded with DynamicComponentLoader.loadNextToLocation are currently not getting included into batarangle.

Great work otherwise!

Cannot build: Cannot find module 'angular2/src/core/linker/element_injector'.at line 46 col 33

In backend/adapters/angular2

Line 46 col 33: import {DirectiveProvider} from 'angular2/src/core/linker/element_injector';
Should be import {DirectiveProvider} from 'angular2/src/core/linker/element';

Sorry I don't have time to create a PR at the moment; would do otherwise
Hopefully it'll help people fix the issue if/when they run into it until it's fixed

Controller Logic for Component Tree

Fix linting errors

Lint errors within backend/adapters/angular2.ts file need to be addressed

Cleanup/Refactor Developer Preview

Objective: Clean house and lay down the foundation for the next phase of features.

Concerns

• Simplify directory structure @igor-ka
• Remove unused code features @vanessayuenn
• Document remaining code @vanessayuenn
• Fix ts compiler warnings @vanessayuenn #41
• Write unit tests
• Update type declarations (see angular/angular#5248 & wiki)

Improve README

Objective: Provide everything needed to get up and running as soon as possible, whether you're a contributor or an end-user.

Concerns

• We need a section on running tests locally.
• There's no LICENSE mentioned anywhere.
• Link to more detailed (user-case specific) docs (e.g. CONTRIBUTING.md, DEVELOPER_README.md, etc...)
• Link to pre-packaged releases
• Some art - the logo and maybe some screenshots - to enhance what is a pretty good description [1].
• Update slack join link
• Add known issues current limitations section
  • mention the Debug View Listener and ng.probe (see #71)
• Add future plans section

[1] We should probably remove any references to a release date.

Render the Tree of Components in an HTML-like syntax

We need to render a tree like structure into an "Angular" panel of Chrome Dev Tools to show an HTML like representation of the component tree with mock data.

1. Add an "Angular" panel to Chrome Dev Tools
2. Bring immutable into the build and potentially have a proper way to include it in the project with <script> tag inclusion as a fallback for now.
3. Create a mock data lists of lists of lists.....representation of the component tree
4. Render it in "Angular" panel using an HTML like representation.

Build more examples

Objective: Provide a playground of different kinds of Angular application and a showcase of the tool's capabilities across them.

Concerns

• The goal should be to demonstrate a variety of data-flows (one-way/two-way), data structures (immutable collections, streams, primitives, etc...)
  • A potential consideration of different backends (e.g. REST, Firebase, Relay, etc...) might also be interesting – especially later on
• I'd be nice if the "barrier to play" here was extremely
  • I'm not against us hosting them
  • Support for 'Deploy to Heroku' might also prove helpful to experimentation
• We probably need some Angular1 applications too...

/cc @AbdellaToronto

Traverse Algorithm for a Tree of Components

Once a reference to a root component has been retrieved a tree of components needs to be traversed to extract useful information. This need to be wrapped into some kind of structure to pass further to display.

Install issues

Went through the instructions but now getting this error:

Bring ES6 or TypeScript support for this repo

Add a build and packaging process to this repo so that this extension can be developed in ES6 or TypeScript, as per investigation.

Throw a more descriptive error instead of 'ng is not defined'

This happens when the default AppViewListener is not bound to DebugElementViewListener during bootstrapping of the app (see issue #71).

• include this instruction somewhere explicit (will be addressed in #67)
• throw a more descriptive error so people are not confused.

Provide contribution guidelines

Need to think of proper guidelines documents so as to make external contributions easy, and smooth out the on-boarding experience.

Show components' properties & events in tree view

Extract properties and events from debug element and show it in the info panel.

Stickers!

I suppose a logo is required first, but afterwards, maybe something aligned with this spec?

Logo

Let's propose some Logo designs

Investigate why browserify is needed for test to run properly

Without browserify, failing tests cause indefinite hanging. (See comments in #72). Since the tests are already getting bundled by webpack, running it through browserify is redundant. Find out how we can take out browserify without tests hanging.

Conditionally enable the panels based on the presence of the angular framework

Provide logic to find out if Angular 2.0 is used within the context of the inspected application.

If Angular 2.0 is present, show our component inspector and the angular panel, otherwise show nothing.

Need to investigate on how to do that, the answer might come from the angular team. This is inspired by the similar check present in React Dev Tools extension.

gulp build produces incorrect output on windows

When trying to build with gulp build, the transpiled typescript files gets put in app\app\ts this is because, gulp-rename does not normalize the directory names, so the line path.dirname = path.dirname.replace('app/ts', 'js'); will actually do nothing on windows, since path.dirname will have \ instead of / in the path.
By adding the line path.dirname = path.dirname.replace('app\\ts', 'js'); after that one, everything works in windows too, this is a workaround though, since I think the real solution is to fix gulp-rename.

Developer README

Objective: Eliminate issues (reported and unreported) raised by developers trying to setup a developing environment or getting the Developer Preview up and running.

Concerns

• There are actually no explicit instructions as to how to go about making changes to the codebase.

Related: #57, #41, #60, #59