Debugging
=========

As described in other places, the code generated by opal and the vienna build tools is not very easy to read, which can become a problem when debugging errors in code. A lot of the properties and methods added to javascript objects are very unfriendly and are often coded. For example, searching a constant uses the `.cs()` method found on every ruby object, and a long chained command might contain many of these method calls before an error occurs, making it difficult to see what is going on.

Stack traces
------------
The ruby stack trace is a great (and often only) place to catch errors. The ruby stack trace lists all the method calls that lead to an error. Opal provides a stack trace, which is available within the browser. Opal additionally adds some extra information on the stack trace. Every method call lists the file and line number that the method implementation is on (in order), but in addition to ruby, opal lists the receiver of the method call (using `inspect`) as well as all the arguments passed to a method. This clearly helps to identify problem code. Inspecting the arguments passed to methods quickly helps to identify where a problem occurred (for example, seeing a `nil` passed into a method is often a good indication that something has gone wrong).

### Example stack trace

Create a new project and enter the code into the document. This is an obvious error, but works well to show the problem.
  
    def something(a, b)
      raise a
    end
    
    def something_a(a, b, c)
      something "adam", [a, b, c]
    end

    something_a 100, 200, 400

Here we know eventually `something` will be called which will raise an error. So on running the given file, the console shows us the following error:

    !!!plain
    RuntimeError: adam
      from request/request.rb:29:in main.something("adam", [100, 200, 400])
      from request/request.rb:33:in main.something_a(100, 200, 400)

The output is clean and simple. The error print out is on the top string. The stack is listed to the left with the filename and line number of each method in the stack. Now, instead of the usual ruby method of just listing the method call, opal lists the receiver (using `inspect`), the method call as expected but also every argument passed to the method (again using `inspect`). It is very easy now to follow what is being passed to what, and where possible errors come from. And, as expected, execution stops on the error.

### Dealing with null and undefined

Occasionally, when writing code that talks to javascript objects, it is possible that null and undefined might slip into the ruby side of things. Trying to send messages to either of these will result in an error. To assist in point out these errors, opal marks a method which takes one of these natives as a warning in the stack trace (supported by Firefox, Safari, IE8, Opera, Chrome) as an indication that this might be the root of the problem. It is not always the cause of the problem, as some methods might accept these objects, but it is a useful indication for most circumstances. Also, any object that slips in which is not a ruby object (like a JSON object for instance) will also get marked with this warning. Try the following code to see an example:

    def some_method(a, b, c)
      puts a
      puts b
      puts c
    end
    
    some_method 10, 20, `null`

Which should produce the following stack trace:

    !!!plain
    RuntimeError
      from browser_test.rb:1: in main.some_method(10, 20, <null>)
      
The second output line should be marked in yellow, or however your browser console identifies warnings. Try a different browser if you do not notice a difference.