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

Summary

• Description
• Getting Started
  • Using a CDN
  • Using NPM
• API
• Options
• Contributing
  • Getting started
  • Pull Requests
• Collaborators
• License

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:

• React (using CDN): https://github.com/perry-js/perry-react-cdn-example
• Vanilla (using CDN): https://github.com/perry-js/perry-vanilla-parcel-example
• Vue (using CDN): https://github.com/perry-js/perry-vue-cdn-example

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

• Armando Magalhaes ([email protected])
• Guilherme Lima ([email protected])
• Vitor Margis ([email protected])
• Jean Baudin ([email protected])
• Nayara Alves
• Iago Angelim Cavalcante ([email protected])

License

Perry is licensed under MIT.