This can be used in a few ways:
- The UI lets you run code directly in the browser and explore the trace. It's deployed to https://brokensandals.github.io/blunt-instrument/ and the source code is in packages/blunt-instrument-ui.
- The libraries can help you build interactive explanations of algorithms. You can evaluate arbitrary code at runtime and get programmatic access to the full trace. Jump to the blunt-instrument-eval README to get started, or see https://brokensandals.github.io/blunt-instrument/fib-call-tree.html for a simple example of usage in the browser.
- The Babel plugin can instrument your code for troubleshooting purposes. See example-plugin-config to see how.
- Currently the UI naively loads the entire trace into memory, so it can't handle large traces yet. (Any fully-instrumented real-world software is going to produce large traces, so I'd like to fix this.)
- Support for
for awaitloop syntax is not yet implemented.
- As mentioned in Enabling and Disabling Tracing, turning the instrumenter on/off for individual lines currently has some gotchas.
- When tracing assignments such as
x.prop = zor
x[index] = z, the trace will include the initial value of
xand the results of
z, but not the final value of
xafter modification. In the future an additional trace event type may be added to track the final value of
- When tracing method calls such as
x.y(), the trace will include the value of
xand the result of
x.y(), along with the trace of the
ymethod (if it was instrumented). But it will not include the
x.yfunction object itself. (This might be fixed in the future, but it seems to be cumbersome to do without changing program semantics.)
- When tracing postfix increment/decrement operators
x--only the expression result (which is equal to
x) is traced, not the new value after assignment. In the future a trace event type may be added to track the effect of the assignment.
- When it encounters a
Proxyobject the tracer will log/display it as if it were the target object. (I think it's impossible by design to universally detect when an object is a Proxy, but it seems possible via monkey-patching to track proxies that are created after the tracer initializes. So this may be partially addressed in the future.)
Clone this repo and run
npm install to install dependencies, then run
npx lerna bootstrap to link the packages together.
This is a multi-package project managed using lerna.
Each package is in a subdirectory of the
Jest and Babel config are at the root and apply to all packages except
blunt-instrument-ui, whose babel/webpack/jest config are managed by create-react-app.
Build and test commands can be run from the root directory.
npm run build:cjs or
npm run build:cjs:watch to build the library packages.
You must do this before running tests, and you must rebuild a package before changes to it will affect other packages' tests.
npm test or
npm run test:watch to run the unit tests.
test:watch in the root directory will not run the UI's tests.
You can run
npm test in
packages/blunt-instrument-ui to watch the UI tests.
Some of the snapshot tests are a bit sensitive to the version of Node you're running - for example, in 12.16.0 the
name property is present on some functions for which it is missing in 12.13.1.
I need a better strategy for dealing with this, but my current aim is to check in the results corresponding to the latest version of Node 12.
npm start to run the UI locally.
npm run build to build all packages, including the UI and ESM builds of the libraries.
Bug reports and pull requests are welcome on GitHub at https://github.com/brokensandals/blunt-instrument.
This is available as open source under the terms of the MIT License.