Skip to content
/ perry Public

Painless and agnostic front-end bug reporting. Collect logs, errors, clicks, and session data easily.

License

Notifications You must be signed in to change notification settings

perry-js/perry

Repository files navigation

Perry is a spy. His job is to help finding bugs in your application.

module formats: umd, cjs, esm CodeFactor BCH Compliance


Summary

Description

Perry.js is an Agnostic Bug Reporter tool that you can just plug in any website.

It allows you to record bug reports in web applications regardless of how they're built. It supports a programmatic API but also comes with a Preact Widget that can be loaded on the fly (thanks to Webpack Code Splitting).

You can learn more about it's capabilities at https://perry-js.netlify.com/

Perry.js is still in active development and can be experimented in internal environments.

We still do not recommend Perry for log transporting, but we do recommend giving it a try for QA bug reporting.

You can find some implementation examples in these repo's:

More examples are being built currently too.

You can track these implementations here: #52

Getting started

Using a CDN

Disclaimer: We still didn't deployed Perry into a CDN.

Meanwhile, you can experiment using the current netlify build.

<script src="https://perry-js.netlify.com/bundle.js"></script>
<script>
  /* This is an example plugin for handling perry's report */
  function ConsoleLogPlugin(reportInfo) {
    console.log("[Perry Report Info]:", reportInfo);
    console.log("[Perry Report Info]:", [
      "",
      "This was printed by the ConsoleLogPlugin.",
      "It is implemented inline into this test page.",
      "To know more about how to implement a Perry Plugin:",
      "Checkout this page src code or the github repository."
    ].join("\n"));

    alert([
      "[Perry Report Info]: Please check your console logs to see the recording report.",
      "Sorry for the alert as well, we'll get rid of it soon! <3"
    ].join("\n"));
  }

  /* Initialize Perry.js */
  const perry = new window.Perry({
    /* Enables log recording */
    log: true,
    /* Enables click recording */
    clicks: true,
    /* Enables screen recording */
    enableScreenRecording: true,
    /* Plugins are ways to handle the bug reporting submission */
    plugins: [ConsoleLogPlugin]
  });

  (async () => {
    /* Starts Perry Recorder */
    await perry.start();

    /* Stops Perry Recorder */
    await perry.stop();

    /* Submit's Perry Report */
    await perry.submit({
      title: 'test-report',
      description: 'A test report'
    });

    /* You can aso render Perry Widget for UI Control */
    await perry.render();
  })();
</script>

Using NPM

Disclaimer: We still didn't deployed Perry into NPM properly.

This documentation is stated here as a demonstration of how it will look like.

Installation

npm install --save perryjs

Usage

import Perry from 'perryjs';

/* This is an example plugin for handling perry's report */
function ConsoleLogPlugin(reportInfo) {
  console.log("[Perry Report Info]:", reportInfo);
  console.log("[Perry Report Info]:", [
    "",
    "This was printed by the ConsoleLogPlugin.",
    "It is implemented inline into this test page.",
    "To know more about how to implement a Perry Plugin:",
    "Checkout this page src code or the github repository."
  ].join("\n"));

  alert([
    "[Perry Report Info]: Please check your console logs to see the recording report.",
    "Sorry for the alert as well, we'll get rid of it soon! <3"
  ].join("\n"));
}

/* Initialize Perry.js */
const perry = new Perry({
  /* Enables log recording */
  log: true,
  /* Enables click recording */
  clicks: true,
  /* Enables screen recording */
  enableScreenRecording: true,
  /* Plugins are ways to handle the bug reporting submission */
  plugins: [ConsoleLogPlugin]
});

(async () => {
  /* Starts Perry Recorder */
  await perry.start();

  /* Stops Perry Recorder */
  await perry.stop();

  /* Submit's Perry Report */
  await perry.submit({
    title: 'test-report',
    description: 'A test report'
  });

  /* You can aso render Perry Widget for UI Control */
  await perry.render();
})();

API

Method Signature Description
constructor new Perry(options: PerryOptions): Perry Returns an instance of Perry.
notify perry.notify(error: Error): Promise<void> A programatic API so you can let perry know of errors without it having to catch them. Useful when handling errors.
render perry.render(): Promise<void> Fetches the Perry Widget component, appends a #perry-widget element into the document body and renders Perry Widget inside of it.
start perry.start(): Promise<void> Tries to start the perry watcher. If something goes wrong, it will stop it and throw an error.
stop perry.stop(): Promise<void> Stops the perry watcher.
submit perry.submit(reportInfo: IPerryReportInfo): Promise<IPerryReport> Aggregates the whole reporting session into the structure defined in the IPerryReport interface, invokes all plugins giving it as an argument and then returns it. Resolves after executing all the plugins configured.

Options

Option Description Type Default
log Enables console.log() calls to be monitored boolean false
warn Enabled console.warn() calls to be monitored boolean true
error Enabled console.error() calls to be monitored boolean true
clicks Enables a listener on document.onclick with screen and viewport information boolean false
cookies Returns the customer browser cookies in the final report boolean false
localStorage (WIP) Returns localStorage data in the final report boolean false
sessionStorage (WIP) Returns sessionStorage data in the final report boolean false
clearOnReload Will clear the perry store everytime you reload it's instance boolean false
clearOnStart Will clear the perry store everytime you start a bug reporting session boolean true
ignoreScriptErrors Ignore's external script error messages. boolean false
enableScreenRecording Enables Screen Recording through the MediaDevices and MediaRecorder API's. boolean true
plugins Allows you to inject handlers for the reports generated by Perry. (e.g.: You can send data to your API using it). ReadonlyArray<(reportInfo: PerryReportInfo) => void> []

Contributing

See the CONTRIBUTING.md file.

Collaborators

License

Perry is licensed under MIT.