Debugging

This debugging guide assumes you have setup the project correctly, see Build Instructions.

To run the local demo and test your MusicXML files:

• run npm install if you haven't already (usually only needs to be done once, or when the package.json was updated)
• run npm start in your cloned repository folder
• open http://localhost:8000/ in your Browser
• To render your own MusicXML file, drag&drop it into the window.
• It should look similar to our public demo, except for a different interface and state of code.
  
• There are url parameters you can add, like ?debugControls=0:
  localhost:8000?debugControls=0
  For further parameters, take a look at index.js (search for param, e.g. paramShowControls)

The public demo is on the state of the last release, which can be useful to compare.

Try Exploring the Demo!

In the local and public demo, the osmd object is accessible in the console. You can call e.g. osmd.version or osmd.setOptions() (see here), or explore osmd.sheet for useful info about the sheet and how OSMD processed it, like measures or meta info (title, etc). After each change, you need to call osmd.render() to see the effects in the score (or click the Re-render button in the local demo).

When you make changes to the code and npm start (the webpack-dev-server) is still running, it will recompile necessary sources and your Browser page will refresh.
If you change method or class signatures however, webpack-dev-server might encounter build errors, and you'll have to stop the server, npm run build and npm start again.

The local server will keep running until you close it (Ctrl-C in console), and you can't run two servers for this demo at the same time (on the same port).

For breakpoints, you can e.g. use the Chrome Developer Tools. If you only get a few lines of minified code in the Sources window, you might have to add the source map (right-click in the editor), or do npm run build:webpack-dev, which gives you a non-minified source. (then restart the server)

You can also do npm run test to run our karma tests and see if you broke anything. No test should fail, except if the timeout is too short, see Testing.
Also, try Visual Regression Testing.

Debugging in Visual Studio Code

More convenient debugging can be done e.g. in Visual Studio Code (not Visual Studio!) and a Chrome or Edge instance, by putting this launch.json in your osmdFolder/.vscode/:

{
    "version": "0.2.2",
    "configurations": [
      {
        "type": "chrome",
        "request": "launch",
        "name": "Launch Chrome Debugging",
        "url": "http://localhost:8000"
      },
      {
        "type": "msedge",
        "request": "launch",
        "name": "Launch Edge Debugging",
        "url": "http://localhost:8000"
      }
    ]
}

Now you can simply press F5, or go Run and Debug -> Launch Debugging to start debugging. Set breakpoints in VSCode with F9. (at best after OSMD has finished loading initially)

Update: You don't have to install the VSCode Debugger for Chrome extension anymore, which is now deprecated.
Also, the launch.json has changed.

If the debugging doesn't work, try restarting VSCode and Chrome/Edge, and updating your VSCode.

For further debugging options, see VSCode's debugging pages.

Linting

Your code will have to pass linting (code style guidelines) if you want to commit it to our repository (e.g. in a Pull Request). Run npm run lint to call eslint. This will also automatically be executed with npm run build.

The linting rules are configured in .eslintrc.js. (advantage over .json: .js can use comments)

If using VSCode, it's helpful to install the ESLint extension, to automatically check for linting issues while coding. By default, it will only check opened/saved files.

To run ESLint over the whole folder in VSCode (and see the issues in Problems):

• Go to Preferences -> Settings -> Workspace -> search for lint task
• Check the checkbox to enable a task to lint the whole workspace.
• Open the Command Palette (View -> Command Palette)
• Enter run tasks, select Run Task -> eslint -> lint whole folder.

Note: tslint is becoming deprecated and Microsoft (creators of Typescript) are recommending to switch to eslint with typescript plugins and configurations.