A pretty darn cool JavaScript debugger for Brackets

Overview

Theseus

Theseus is a new type of JavaScript debugger for Node.js, Chrome, and both simultaneously. It is an extension for the Brackets code editor.

Theseus is part of a collaboration between the User Interface Design Group at MIT CSAIL and Adobe Research. Though it's a research project, I'm doing the best I can engineering-wise and I'm responsive to bug reports and feature requests. Patches welcome!

Screenshot of Theseus

Features

Real-time code coverage: Theseus shows the number of times that every function has been called next to its definition. Functions that have never been called are also given a gray background. You can watch the code light up as you interact with the web page.

Screenshot of call counts and dead code coloring

Retroactive inspection: Click a call count to see the values of parameters, return values, and any exceptions that have been thrown from that function. It's like adding console.log without having to save and reload.

Screenshot of a single function being logged

Asynchronous call tree: If you click multiple call counts, all invocations of those functions are shown in a tree. When callback functions are called, they show up in the tree under the function that created them, regardless of whether they were called immediately or many ticks later.

Screenshot of multiple functions being logged

Install

  1. Install Brackets Sprint 28 or later.
  2. In Brackets, click the menu item File > Extension Manager...
  3. Go to the "Available" tab of the dialog that appears.
  4. Type "Theseus" in the search box.
  5. Click the "Install" button in the search result for Theseus.

For Node.js support, also run npm install -g node-theseus in a terminal to get the command-line helper. Theseus requires node-theseus 0.2.x.

Usage: Debug JavaScript running in Node.js

Brackets + Node.js

Start your program by running node-theseus app.js (instead of node app.js as you normally would). Theseus will automatically connect to that process.

(You install node-theseus with npm install -g node-theseus)

node-theseus download statistics

Usage: Debug JavaScript running in Chrome

Brackets + Chrome

Open the File menu and put Theseus into the mode for static HTML files:

Brackets + Chrome

Then open an HTML file and start Brackets' Live Development mode by clicking the lightning bolt in the top right corner of the window:

Brackets' lightning bolt

Your page will open in Chrome.

A Handful of Technical Details

Node.js: Files with paths containing node_modules will not be instrumented.

Chrome: Files requested with the URL parameter theseus=no (for example, <script src="script.js?theseus=no" />) will not be instrumented.

Any file containing the (exact) string /*theseus instrument: false */ will not be instrumented by Theseus. You can also use the --theseus-exclude=filename option with node-theseus (which also has some other options that you might find helpful).

Bugs

First, there's a whole wiki page about troubleshooting Theseus. Check it out!

If you come across a bug, submit an issue on GitHub. Include a list of steps we can follow to reproduce the problem, a description of what you saw that seemed broken, and a description of what you expected to see.

Mailing List

Announcements and discussion: https://groups.google.com/d/forum/theseus-discuss

Contributing/Extending

Theseus is a constellation of Node.js modules working together. For contributors, there's a detailed description of how Theseus works, but below is a list of all the modules that you can use to create similar (or dissimilar!) projects.

Patches to any of these projects are welcome. I'll even help you figure out how to do something that doesn't make sense to merge but still deserves to exist.

Theseus, the Brackets extension

JavaScript trace collection

  • adobe-research/fondue: JavaScript instrumentation library. Rewrites JavaScript code so that when it runs, it saves a trace of everything that happened. Theseus uses fondue's API over WebSockets or Brackets' Live Development connection, depending on the context.
  • alltom/fondue-middleware: a connect middleware that processes all JavaScript in .js and .html files with fondue

JavaScript source rewriting

Prototypes

Contributors

  • @alltom. Primary developer.
  • @nhynes. Automatic upgrades, bug-fixes.
  • @MarcelGerber. Made the UI translatable and added German translation.
  • @joelrbrandt. Added the menu item for enabling and disabling Theseus.
  • @larz0. Made Theseus match Brackets' visual style.
  • @jasonsanjose. Sprint 30 compatibility, Edge Code compatibility.
  • @benchuk. Redirect requests to files in /public to root.

Also thanks to the whole Brackets team, and to @alltom's mentors, @rcmiller and @joelrbrandt!

License

Theseus is released under the MIT license.

Comments
  • Unable to debug in Brackets

    Unable to debug in Brackets

    Hi, I am using WIndows and unable to debug in Brackets.

    I have installed Theseus and copied brackets-theseus to extensions/user directory. After that i installed node-theseus using -g option run my app using node-theseus instead of node.

    But still i couldn't debug my files and not getting code coverage etc.,

    Am i missing in something?

    opened by kmatheeswar 19
  • Errors installing Theseus on Brackets (sprint 38)

    Errors installing Theseus on Brackets (sprint 38)

    Hi there,

    I'm having issues installing Theseus for Brackets through the UI. I'm using Brackets (sprint 38 experimental build 0.38.0-12606 (release 4df8afdad)). The installation prompts a generic error in the Brackets UI, and shows in the extension list as having an 'extension error'.

    The Brackets developer log has the following after downloading Theseus and trying to install. I'm new to both projects so I might be missing something simple, but the extra .js extensions seem suspect. The files (sans the .js extensions for the HTML pages) seem to be in the Theseus folder inside the extensions folder.

    GET file://[windowsfileserver]/users$/[username]/AppData/Roaming/Brackets/extensions/user/theseus/package.json.js  require.js:1872
    GET file://[windowsfileserver]/users$/[username]/AppData/Roaming/Brackets/extensions/user/theseus/src/InstallationCorrupt.html.js  require.js:1872
    Uncaught Error: Script error for: package.json
    http://requirejs.org/docs/errors.html#scripterror require.js:163
    Uncaught Error: Script error for: src/InstallationCorrupt.html
    http://requirejs.org/docs/errors.html#scripterror require.js:163
    GET file://[windowsfileserver]/users$/[username]/AppData/Roaming/Brackets/extensions/user/theseus/src/Invitation.html.js  require.js:1872
    Uncaught Error: Script error for: src/Invitation.html
    http://requirejs.org/docs/errors.html#scripterror require.js:163
    GET file://[windowsfileserver]/users$/[username]/AppData/Roaming/Brackets/extensions/user/theseus/src/NewVersionAvailable.html.js  require.js:1872
    GET file://[windowsfileserver]/users$/[username]/AppData/Roaming/Brackets/extensions/user/theseus/src/InvalidVersion.html.js  require.js:1872
    Uncaught Error: Script error for: src/NewVersionAvailable.html
    http://requirejs.org/docs/errors.html#scripterror require.js:163
    Uncaught Error: Script error for: src/InvalidVersion.html
    http://requirejs.org/docs/errors.html#scripterror require.js:163
    [theseus] fsm: -> waitingForApp fsm.js:35
    [theseus] fsm: -> disconnected fsm.js:35
    [Extension] failed to load //[windowsfileserver]/users$/[username]/AppData/Roaming/Brackets/extensions/user/theseus Error: Load timeout for modules: text!package.json_unnormalized2,text!src/InstallationCorrupt.html_unnormalized3,text!package.json,text!src/InstallationCorrupt.html,text!src/Invitation.html,text!src/NewVersionAvailable.html,text!src/InvalidVersion.html
    http://requirejs.org/docs/errors.html#timeout /utils/ExtensionLoader.js:209
    Uncaught RangeError: Maximum call stack size exceeded
    
    opened by yelper 14
  • German translation

    German translation

    Are you interested in a german translation? I'm from germany and your extensions is great (brackets, too), so I could translate the extension into the german language.

    But you may should add more translations into the scr/nls-files, so more words would be translated...

    opened by marcelgerber 9
  • Impossible to debug, slow

    Impossible to debug, slow

    in mid-sized node app, theseus with brackets 25 eats 2+gb of ram and then crashes w FATAL ERROR: CALL_AND_RETRY_2 Allocation failed - process out of memory.

    Also, speed slowdown is like 95-99%.

    You can try it by yourself

    1. clone [email protected]:brunch/brunch.git
    2. coffee -bo lib/ src/ && cd ../
    3. ./brunch/bin/brunch new test
    4. cd test
    5. node-theseus ../brunch/bin/brunch build
    opened by paulmillr 9
  • Allow Proxy Server port configuration

    Allow Proxy Server port configuration

    My project connects to a server in a different domain but is allowed to fetch data because CORS allows localhost:8888. I can't change the server to allow localhost:3000. It might be easier for me to beg my co-worker to change the server than for you to allow configuring the port, but I'm afraid someone else may end up with the same problem.

    opened by Subterrane 6
  • Theseus will not debug in Chrome when using Proxy Mode settings

    Theseus will not debug in Chrome when using Proxy Mode settings

    Tom commented in a previously closed issue:

    I just realized that I misunderstood what the project URL setting did. I'll test Theseus with it more to see if I can make it less confusing

    When setting the project in Brackets to serve files from a specified url, Theseus does not report debug info. This is true whether the File menu selection is set to 'Mode: Serve files from disk' or 'Mode: Proxy to localhost:3000'. Even if the files are being served from the domain localhost and port 3000, Theseus is not active in Brackets.

    This effectively restricts Theseus use in Chrome to the Brackets internal http server.

    opened by Revlin 6
  • Theseus is causing New Button in Brackets inline editor not to function correctly.

    Theseus is causing New Button in Brackets inline editor not to function correctly.

    Clicking on new rule button while in the CSS Quick edit, opens and closes the list of stylesheets instantly.

    https://github.com/adobe/brackets/issues/6641

    opened by RaymondLim 5
  • Cannot include nan.h

    Cannot include nan.h

    Hy..

    Tried installing node-theseus with "npm install -g node-theseus" on windows 8 but get this compile error

      bufferutil.cc                                                                                                                                                                                                                         
    ..\src\bufferutil.cc(15): fatal error C1083: Cannot open include file: 'nan.h': No such file or directory [C:\Users\João Henriques\AppData\Roaming\npm\node_modules\node-theseus\node_modules\ws\build\bufferutil.vcxproj]              
      validation.cc                                                                                                                                                                                                                         
    ..\src\validation.cc(14): fatal error C1083: Cannot open include file: 'nan.h': No such file or directory [C:\Users\João Henriques\AppData\Roaming\npm\node_modules\node-theseus\node_modules\ws\build\validation.vcxproj]              
    
    opened by jfhenriques 4
  • Custom serialization [feature request]

    Custom serialization [feature request]

    The Theseus log for instance displays HTML elements as [object Text] and [object HTMLDivElement] etc... It would be great to allow custom serialization of objects.

    opened by vojtajina 4
  • failed to get tracer instance

    failed to get tracer instance

    Trying to get up and running with Brackets and Theseus. Brackets Live Preview works but cannot seem to connect with Theseus.

    From the logs I see "failed to get tracer instance" / "Reference Error: __tracer is not defined".

    I'm not expert on this stuff and tried to sift through the extension and fondue source but couldn't find where it is suppose to instantiate this instance.

    I also tried disabling all other extensions but no luck.

    OS X 10.9.2 Chrome 34.0.1847.131 (265687) Brackets 38 (also tried building from source, version 40)

    opened by ohnnyj 3
  • redirect request from brackets live development for public dir files to ...

    redirect request from brackets live development for public dir files to ...

    Hi first pull request :) This path fixes the problem where one starts live development and get the url set to http://...../public/index.html - where node does not allow this. This happen because live dev does not know about node being attached. There for redirection fixes this issue.

    opened by benchuk 3
  • Cannot install on Windows 10

    Cannot install on Windows 10

    OS: Windows 10 Version: Version on brackets registry Brackets version: 1.13

    Problem: Whenever I attempt to install theseus-brackets, i get the error: "Extension failed on startup" or something like that. I notice in the devtools, it says,

    C:/Users/[MY USERNAME]/AppData/Roaming/Brackets/extensions/user/theseus - Error: Module name "view/PanelManager" has not been loaded yet for context: _
    

    I would really like this issue fixed because this extension looks like it hols lots of promise.

    opened by TheGreatRambler 5
  • Installation fails from Brackets IDE

    Installation fails from Brackets IDE

    Installing Theseus from the Brackets IDE fails every time. It fails when pulling the zip from AWS, I never get to the point where I can click the second "install" button.

    opened by Tha1der 3
  • Launching live preview fails in brackets 1.7 with theseus 0.4.19

    Launching live preview fails in brackets 1.7 with theseus 0.4.19

    Attempting to launch live preview on any html file simply says "unable to load live preview page" and links to the brackets troubleshooting article. This only happens when the theseus plugin is enabled in brackets.

    opened by chuckdries 0
  • Empty log when using Theseus

    Empty log when using Theseus

    When I debug javascript with, I do get to see the labels indicating calls. But when I click on a label I see an empty log, so no information about the calls at all.

    In de Development Tools of Brackets I see this error:

    Agent-chrome.js:274 Uncaught TypeError: Cannot read property 'wasThrown' of undefined

    I suspect this to be the cause of the problem.

    opened by smartscripts-nl 6
  • es6 arrow operator not working

    es6 arrow operator not working

    for code

    var a = [{_id:123}];
    var c = {};
    a.forEach((d) => {
        c[d._id] = true;
    })
    

    Got following error

    exception during parsing /Users/parinkumar.katariya/apps/elastic/test.js Error: Line 504: Unexpected token >
        at throwError (/Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:1156:21)
        at throwUnexpected (/Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:1213:9)
        at parsePrimaryExpression (/Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:1561:16)
        at /Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:3598:38
        at trackLeftHandSideExpressionAllowCall (/Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:3493:61)
        at parsePostfixExpression (/Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:1697:20)
        at /Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:3598:38
        at parseUnaryExpression (/Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:1777:16)
        at /Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:3598:38
        at parseMultiplicativeExpression (/Users/parinkumar.katariya/.nvm/versions/node/v5.6.0/lib/node_modules/node-theseus/node_modules/esprima/esprima.js:1783:20)
    
    opened by parinck 4
Owner
Adobe Research
Adobe Research
Well-formatted and improved trace system calls and signals (when the debugger does not help)

ctrace Well-formatted and improved trace system calls and signals (when the debugger does not help). Why? Awesome tools strace and dtruss have only on

Aleksandr Komlev 117 Dec 27, 2022
Dynamic tracing for javascript, in javascript (similar dtrace, ktap etc)

jstrace Dynamic tracing for JavaScript, written in JavaScript, providing you insight into your live nodejs applications, at the process, machine, or c

null 387 Oct 28, 2022
A tiny JavaScript debugging utility modelled after Node.js core's debugging technique. Works in Node.js and web browsers

debug A tiny JavaScript debugging utility modelled after Node.js core's debugging technique. Works in Node.js and web browsers. Installation $ npm ins

Sloth 10.5k Dec 30, 2022
An lldb plugin for Node.js and V8, which enables inspection of JavaScript states for insights into Node.js processes and their core dumps.

Node.js v10.x+ C++ plugin for the LLDB debugger. The llnode plugin adds the ability to inspect JavaScript stack frames, objects, source code and more

Node.js 1k Dec 14, 2022
Pretty-print-json - 🦋 Pretty-print JSON data into HTML to indent and colorize (written in TypeScript)

pretty-print-json Pretty-print JSON data into HTML to indent and colorize (written in TypeScript) 1) Try It Out Interactive online tool to format JSON

Center Key 87 Dec 30, 2022
Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

JavaScript-med-Ramverk-Laboration-3 Grupprojektet för kurserna Javascript med Ramverk och Agil Utveckling. Utvecklingsguide För information om hur utv

Svante Jonsson IT-Högskolan 3 May 18, 2022
A pretty cool org-mode -> interactive blog post tool

Radish A kinda-cool org-mode -> interactive blog post tool written with and for Clojure(script). Here are two example posts created with this tool: Ra

adam-james 46 Dec 28, 2021
Pretty Cool Elements

Pretty Cool Elements Social Media Photo by Jamison McAndie on Unsplash This module is a follow up of this Medium post, and it provides element mixins/

Andrea Giammarchi 36 Dec 23, 2022
Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

null 4 May 3, 2022
Kurs-repo för kursen Webbserver och Databaser

Webbserver och databaser This repository is meant for CME students to access exercises and codealongs that happen throughout the course. I hope you wi

null 14 Jan 3, 2023
A Front-End JavaScript Debugger

vDebugger · English | 简体中文 A Front-End JavaScript Breakpoint Debugger. Make it possible to debug your JavaScript in browser, Node.js, JavaScriptCore o

Wechat.js 6 Nov 8, 2022
Node.js debugger based on Blink Developer Tools

Node Inspector Overview Node Inspector is a debugger interface for Node.js applications that uses the Blink Developer Tools (formerly WebKit Web Inspe

null 12.6k Dec 29, 2022
Well-formatted and improved trace system calls and signals (when the debugger does not help)

ctrace Well-formatted and improved trace system calls and signals (when the debugger does not help). Why? Awesome tools strace and dtruss have only on

Aleksandr Komlev 117 Dec 27, 2022
Visual debugger for framer-motion

Visual debugger for framer-motion Demo install npm install tracer-motion --save-dev # or yarn add tracer-motion --dev usage import { motion } from

Siddharth Kshetrapal 69 Oct 9, 2022
Time-traveling debugger for Svelte applications

DeLorean The first time-travelling debugger for Svelte applciations DeLorean is a debugging tool for Svelte developers. It records snapshots when a ta

OSLabs Beta 60 Oct 8, 2022
WIP: Hevm based debugger for hardhat-huff projects

Huff Debug An easy hevm debug integration for hardhat-huff projects What does it do: Speed up your development experience by gaining rich feedback in

Huff 6 Jul 15, 2022
Nodejs agent for Sidekick open-source live application debugger

Sidekick Agent NodeJS Sidekick agent Nodejs is a Nodejs library that communicate with Sidekick broker to inspect, monitor and debug your application o

Sidekick 12 Nov 8, 2022
Pretty diff to html javascript library (diff2html)

diff2html diff2html generates pretty HTML diffs from git diff or unified diff output. Table of Contents Features Online Example Distributions Usage Di

Rodrigo Fernandes 2.3k Dec 31, 2022
Pretty diff to html javascript cli (diff2html-cli)

diff2html-cli Diff to Html generates pretty HTML diffs from unified and git diff output in your terminal Table of Contents Features Online Example Dis

Rodrigo Fernandes 404 Dec 19, 2022
Pretty diff to html javascript library (diff2html)

diff2html diff2html generates pretty HTML diffs from git diff or unified diff output. Table of Contents Features Online Example Distributions Usage Di

Rodrigo Fernandes 2.3k Dec 29, 2022