AXElements 0.6.0beta1

data/docs/Acting.markdown

@@ -0,0 +1,340 @@
+# Actions (a.k.a. The Fun Part)
+
+Actions are how you drive the user interface. They can be anything
+from showing a menu to dragging a window, but are often simple things
+like pressing a button. Most actions are subtly different cases
+of the same thing, but it is important to understand the differences
+and when to use different actions.
+
+There are three types of actions, those provided by the accessibility
+API as direct calls, those provided by accessibility APIs as keyboard
+simulation, and those that are provided by the CGEvents API. In most
+cases you can use at least two types of actions to achieve the desired
+effect and each type of action has its own pros and cons to consider.
+
+## Interface
+
+Though there are three different APIs under the hood, they are exposed
+through a common interface via the DSL methods in
+{Accessibility::Language}.
+
+    app = Accessibility.application_with_name 'Terminal'
+    press app.main_window.minimize_button
+    type "\\CMD+M", app
+    click app.main_window.minimize_button
+
+The above example demonstrates performing actions using the DSL
+methods. The DSL methods are always some kind of action, such as
+{Accessibility::Language#drag_mouse_to drag\_mouse\_to}, or
+{Accessibility::Language#set_focus set\_focus} to name two.
+
+The point of the DSL is to put the actions at the front of statements
+in order to separate verbs from nouns. In this way, scripts should
+resemble instructions that you might give for reproduction steps in a
+bug report---they should read like they were instructions for
+a person. This style should make it easier to think about writing
+scripts and it should also give better hints at when to refactor
+code into helper methods like `log_in_as:with_password:`.
+
+If you tried out the code snippet above you might notice the
+difference between the APIs (you also might notice that the second
+command does not work, it is a work in progress :(). In the first
+case, `press` was using the actions provided by the accessibility APIs
+to call the press action on the minimize button for the window, in the
+second case we used `type` to type in the hot key for minimizing a
+window, and in the third case we used `click` from the CGEvents APIs
+to actually move the mouse cursor to the button and generate a click
+event.
+
+## Accessibility Actions
+
+Actions like `press` use the accessibility APIs and show up in the
+list of actions returned by {AX::Element#actions}. These actions will
+also show up in the Accessibility Inspector in the Actions section.
+
+You may have noticed that {Accessibility::Language#press press}
+shows up as `AXPress` for buttons when you view them with the
+Accessibility Inspector or by calling {AX::Element#actions}. This is
+because we do name translation with accessibility actions just like
+when accessing attributes as shown in the
+{file:docs/Inspecting.markdown Inspection tutorial}.
+
+Accessibility actions are the simplest and fastest way to trigger
+actions. They use the accessibility APIs to talk directly to the
+application to call the same methods that would be called when
+you interact with the application with the mouse or keyboard, but
+without having to use the mouse or keyboard.
+
+## Setting Attributes
+
+Though it is not really an action, some attributes can have their
+values changed through the accessibility APIs. The
+{Accessibility::Language} module has two methods, `set` and
+`set_focus`, which allow you to change the value for certain
+attributes.
+
+In the Accessibility Inspector, a writable attribute will have `(W)`
+next to the attribute name, and the programmatic way to tell if an
+attribute is writable is to call {AX::Element#attribute_writable?} and
+pass the name of the attribute as a parameter:
+
+    app.main_window.attribute_writable? :size
+    app.main_window.attribute_writable? :title
+
+You can only set an attribute if it is writable. When you have an
+attribute that is writable, and you would like to change it, then you
+simply need to call `set`:
+
+    set app.main_window, size: [500, 500].to_size
+
+The first parameter is the element, and the second parameter is a
+key-value pair with the attribute as the key and the value as the
+new value.
+
+`set_focus` is just syntactic sugar for `set` where the key-value is
+set for you and the only parameter you provide is the element you want
+to set focus to:
+
+    set_focus app.main_window.text_field
+
+Though, `set` itself has a special case. The second most frequently
+changed attribute for a element is the `value`, it is used almost as
+much as `focused`. For this case, you can pass anything that is not a
+key-value pair to `set` and it will be assumed that you want to change
+the value of the `value` attribute:
+
+    set app.main_window.text_field, 'Mark Rada'
+
+Another important detail that you might be curious about is that we
+called `to_size` on the first snippet showing how to set an
+attribute. The developers of MacRuby have added a feature that allows
+you to pass an array as an argument when you would normally be
+expected to pass a structure such as a `CGPoint`. Since AXElements
+APIs inherently need to handle any type of object, it is not sane to try
+and do the same type of run time type analysis. In its place, I have
+provided some convenience methods for {NSArray arrays} to let you
+quickly transform them to the appropriate type of object. In my
+opinion, you should just use the proper type of object in the first
+place and avoid the overhead.
+
+### You Want To Use Actions
+
+The advantage to using accessibility actions is that they are usually
+much easier to use than the other APIs. Accessibility actions are
+usually synchronous and so your scripts will not need to worry about
+waiting for animations to complete. The only complication is that
+sometimes an action is not synchronous and there is no good way to
+tell if an action is synchronous without looking at the underlying
+code.
+
+### Asynchronous Problems
+
+Problems with synchronous behaviour will occur with all the types of
+actions, but less often with accessibility actions, so you should
+always try thing out first in the console to make sure. A good rule of
+thumb is that anything that looks like it would take a noticeable
+amount of time, and is not an animation, will probably be
+asynchronous. An example of this would be having to load data from a
+database (read: separate process, across a network, etc.) such as in
+the Marketcircle server admin apps or the Billings Pro preferences.
+
+Asynchronous behaviour can often be worked around by using
+accessibility  {file:docs/Notifications.markdown notifications} or by
+simply calling
+[`sleep`](http://rdoc.info/stdlib/core/1.9.2/Kernel#sleep-instance_method).
+Notifications have some interesting caveats that are covered in their
+own tutorial and so it is much easier to `sleep`.
+
+However, using `sleep` to solve the problem of asynchronous waiting is
+like using a steak knife for brain surgery. Unless you can control the
+environment when the script is running, you will need to sleep for
+longer periods of time than you really need to; even when you have
+quite a bit of control you might still have the occasional instance
+where a database fetch takes longer than expected. I would suggest you
+use notifications when you can, and sleep when you cannot.
+
+## CGEvents Actions
+
+CGEvents based actions never directly use the accessibility APIs and
+are implemented at a different level of the GUI stack in OS X (I
+assume). An action that uses CGEvents will actually move the mouse
+cursor around and simulate mouse input at a relatively low level of
+abstraction. However, accessibility information is still used to find
+the point on the screen to move to and click. These types of actions
+are more realistic, more awesome looking, and also more difficult to
+write.
+
+The difficulty in writing the scripts comes from the fact that it does
+not directly communicate with the accessibility APIs. This implicitly
+means that all CGEvents actions are asynchronous, which is the only
+non-trivial complication with using CGEvents APIs.
+
+### CGEvents Goes Where Accessibility Cannot
+
+The benefit of actually moving the mouse will often outweigh the
+downside here. Moving the mouse cursor and generating click events
+allows things like dragging and scrolling which cannot be done using
+the accessibility APIs.
+
+As mentioned earlier, CGEvents doesn't talk to applications in the
+same way that accessibility APIs do, which means that you can use
+CGEvents actions on elements that do not fully support
+accessibility. For instance, text might appear on the UI and have a
+`click`-able link but may not provide an equivalent action to clicking
+on the link; using CGEvents APIs you will only need to move to the
+position of the text and then generate a click event.
+
+### Realism
+
+Since CGEvents actually manipulates the mouse cursor, any script that
+uses the APIs will be more realistic than their equivalent
+accessibility actions. This can make a difference if you are testing
+an app and you are expecting other side effects to occur. For instance,
+what if you implemented a sort of UI element that requires the mouse
+cursor to be near the element for an action to trigger, such as an
+expanding drawer or a folder in the finder. Depending on what you are
+using AXElements for, this may or may not be important to you.
+
+### Underpinnings
+
+An important thing to note is that AXElements always works with
+flipped co-ordinates. The origin, `(0, 0)` is always located in the
+top left corner of the main display. Displays to the left have a
+negative `x` co-ordinate and displays above the main display will have
+negative `y` co-ordinates.
+
+Though the CGEvents APIs are exposed to AXElements through the
+{Accessibility::Language Language} module, there is another thin
+layer between AXElements and CGEvents that abstracts everything that
+AXElements uses.
+
+The between layer is the {Mouse} module, and it is responsible for
+generating events and animating the mouse movements on screen. The API
+that it makes available to AXElements is more fine grained than what
+AXElements makes available to you. There is a lot of room for the
+{Mouse} module to grow and add new features, some of which are noted
+as `@todo` items in the documentation. It may also be necessary in
+the future to make available from AXElements certain options that are
+normally hidden in {Mouse}.
+
+### Where The Mouse Moves
+
+Consider the following:
+
+    move_mouse_to app.main_window.close_button
+
+If you try out that code snippet then you will notice that the mouse
+cursor moves to the button, specifically the center of the button. If
+you use the method to move to another object, such as a button, you
+will again notice that it moved to the center point of the element.
+
+You can call `move_mouse_to` and give it a UI element, but you could
+also be more exact and give it a CGPoint or even an array with two
+numbers. In fact, you could pass just any object as long it implements
+a method named `to_point` which returns a CGPoint object. If you were
+to look at the code for {Accessibility::Language#move_mouse_to} you
+would see that all it does is call `#to_point` on the argument and
+then pass the returned value to the {Mouse} module to actually do the
+work. You could also look at {NSArray#to_point} and find out that it just
+returns a new CGPoint using the first two objects in the array, and
+`CGPoint#to_point` just returns itself (you can't see the
+documentation for the method because of limitations in
+YARD). Similarly, {AX::Element} implements
+{AX::Element#to_point to_point} which not only gets the position for
+the element, but also gets the size and then calculates the center
+point for the element. This is important because you probably never
+want the mouse cursor moving to the top left of the UI element, but
+maybe you don't want the cursor moving to the center either.
+
+If you want to have the mouse move to a location over a UI element
+that is not the center point, then you will need to implement
+`to_point` for the appropriate class. Just remember to follow the
+{file:docs/NewBehaviour.markdown rules} for choosing the proper
+superclasss. For instance, on Snow Leopard you could resize a window
+by clicking and dragging an `AX::GrowArea` object in the lower right
+corner of a window; moving to the center of the element may not
+actually allow the mouse to respond and so you would have to implement
+`to_point` to move closer to the bottom right of the window
+(__NOTE__: I don't know if that is actually true for `AX::GrowArea`,
+it was just meant as an example).
+
+### Dragging
+
+Sometimes you just need to be able to click and drag an element. To do
+this you can only use the CGEvents APIs. Fortunately, click and drag
+is relatively painless with AXElements, the simplest example would be
+something like this:
+
+    # move to the mouse to the starting point
+    move_mouse_to app.main_window.title_ui_element
+
+    # start the click and drag event
+    drag_mouse_to [0, 0]
+
+Pretty cool, eh? The general pattern is to move the mouse to the
+starting point, and then to call `drag_mouse_to` to start the click
+and drag events. In the example, I gave co-ordinates using an array
+with two numbers but you can pass a CGPoint or anything else that
+responds to  `to_point` just like with the other CGEvents actions.
+
+## Keyboard Actions
+
+The final type of action is the keyboard action. Keyboard actions
+live in a world between the accessibility APIs and CGEvent APIs; that
+is, Apple has already done the work of unifying them for me and in a
+way that I would not have been able to do myself.
+
+The keyboard action is a single method,
+{Accessibility::Language#type}, that requires one parameter and
+takes an optional second parameter. The first parameter is simply a
+string that includes which characters you wish to have typed out and
+the second parameter is the UI element for the application where you
+would like to send the keyboard events. Since the second parameter is
+optional, the currently focused app will receive the events if the
+parameter is not used.
+
+    # to a specific app
+    app = Accessibility.application_with_name 'Terminal'
+    type "Hello, world!", app
+
+    # to the focused app
+    type "Hello, world!"
+
+The string that you pass can have some special escape sequences to
+indicate that you want to press command characters or a combination of
+keys at once for a hot key. Details on this are contained in their own
+tutorial, the
+{file:docs/KeyboardEvents.markdown Keyboard Events Tutorial}.
+
+## Mixing In
+
+By now you will have noticed that all the actions have been defined in
+the {Accessibility::Language} name space, which is just a simple
+module. Though, you have been able to use the methods anywhere and in
+any context.
+
+When you load AXElements, by using `require 'ax_elements'`, not only
+will all the code be loaded, but the extra step of mixing
+{Accessibility::Language} into the top level name space will also be
+done for you. The only way to override this behaviour is to load the
+components of AXElements yourself, the details on how to do this are
+left as an exercise to interested parties. :P
+
+## A Note About Caching
+
+You need to be careful when you cache UI element objects. Every time
+that you trigger an action you are intrinsically changing the state of
+an application. State changes will often cause new UI elements to be
+created, recreated, or removed.
+
+For example consider pressing the close button for a window; in this
+case, an entire window and all of its children will disappear and
+become invalid objects. Another case might be pressing the `+` button
+for a table; in this case you have created a new row for the table and
+any cache of the existing rows for the table will not include the new
+element.
+
+The real problem with caching is with the invalid objects. An invalid
+object is poisonous to the MacRuby run time. If you try to access an
+attribute or trigger a search from an invalid then you will cause
+MacRuby to crash.

data/docs/Debugging.markdown

@@ -0,0 +1,326 @@
+# Debugging
+
+This document includes instructions on using AXElements' built in
+tools to help you debug issues with your scripts, or in cases where
+you might find a bug in AXElements itself or MacRuby.
+
+## Trees
+
+Sometimes you need to see the big picture, the whole UI tree at
+once or at least be able to see the root of the hierarchy from where
+you are. For these troubling cases AXElements provides a few tools.
+
+### Text Tree
+
+Printing a text tree is similar to how a UI dump works with
+accessibility on iOS. AXElements does improve a bit on its iOS
+equivalent. Simply using the Accessibility Inspector does not give you
+a good picture of the whole tree and with complicated structures it is
+easy to make mistakes navigating the UI tree.
+
+The text tree comes formatted for you, and you can simply print it out
+to the console. The output uses indentation to indicate how far down
+the tree each element is, and the first element up the tree with one
+indentation level less will always be the parent for an element.
+
+Printing out a text tree in the console is very easy. First you generate
+the text dump and then you print it out:
+
+    puts Accessibility.dump(app)
+
+This method is useful when you are having difficulties with
+search. Sometimes when searching you will end up finding the wrong
+element because your search query was ambiguous and you didn't
+know at the time. Printing out a dump can often be all the help you
+need in order to identify your problem.
+
+However, if the standard `#inspect` isn't doing it for you, you can
+perform your own inspection every element in a tree yourself using the
+built in enumerators. Searches use the {Accessibility::BFEnumerator},
+but the text tree dump method uses {Accessibility::DFEnumerator}.
+
+### Dot Graph
+
+__NOTE__: This feature isn't actually done yet. Coming soon, I promise.
+
+For super fancy text trees, AXElements can generate dot graphs for
+consumption by [Graphviz](http://www.graphviz.org/). In this case, you
+want to call {Accessibility.graph} and pass the root of the tree you
+want to have turned into a dot graph; you will get a string back that
+you will then need to give to Graphviz in order to generate the visual
+graph.
+
+### Text Tree Won't Print?
+
+AXElements isn't perfect and it is possible that an edge case slipped
+between the cracks. However, it's also possible that the problem is
+actually how accessibility information is being vended out.
+
+As an example, Radar #10040865 is a ticket that I filed with Apple
+where they broke accessibility with search fields. The effect to
+AXElements was that you could not search through the menu bar causing
+a text dump to fail in a very difficult to trace manner.
+
+In these cases you will need to use your deductive reasoning to figure
+out where the problem is coming from. Fortunately, I have provided
+some tools to help you along the way.
+
+## All The Way Up
+
+Sometimes you don't need a whole tree to be printed out. Sometimes
+just seeing the path from an element to the top level element is
+enough. {Accessibility.path} is your friend in this case, it will
+provide you with an array of UI element objects, each successive
+element will be the parent of the previous element. This is almost
+like the view that the Accessibility Inspector provides.
+
+## Custom Exceptions
+
+AXElements provides some customized exceptions in the OO layer that
+should help give you much better hints at what went wrong when you
+have a problem.
+
+Custom exceptions have been created to help identify the point of
+failure that would have caused a more cryptic exception to have been
+raised instead. These custom exceptions also capture more metadata
+about the problem that occurred which should give good hints as to what
+went wrong.
+
+### Search Failures
+
+An {AX::Element::SearchFailure `SearchFailure`} will occur when you
+perform an implicit search that fails to find anything.
+
+In cases where implicit searches are chained, which happens frequently
+with deep UI hierarchies, if one of the searches were to fail then you
+would receive a `NoMethodError` about something having
+failed. Sometimes the failure would happen because the search returned
+`nil`, and of course `nil` would not respond to another search, though
+this problem was easy to identify if you are familiar with the
+AXElements source code; in other cases the failure would occur
+somewhere in the search {Accessibility::Qualifier qualifier} or in the
+{Accessibility::BFEnumerator enumerator}, and it was not always clear why.
+
+The other feature of a search failure is that the exception message
+will include an element back trace using {Accessibility.path}. This is
+meant to give a hint about why the search failed.
+
+### Attribute Not Writable
+
+You will receive {AX::Element::ReadOnlyAttribute `ReadOnlyAttribute`}
+exceptions only when you try to set an attribute that is not
+writable. Again, this was originally designed to more easily identify the
+point of failure when you try to write to an attribute that you should
+not write to.
+
+Specifically, `set_focus` is called by methods internally by
+AXElements and at one time it was causing some problems when elements
+were unexpectedly not allowing their `focused` attribute to be
+written.
+
+### Attribute Not Found
+
+A very simple fail safe that AXElements uses is the
+{AX::Element::LookupFailure `LookupFailure`} exception which will be
+raised when you try to explicitly access an attribute which does not
+exist, or at least does not exist for the particular element that you
+are trying to access.
+
+## Not So Custom Exceptions
+
+Sometimes it is possible that the back trace for other exceptions can
+get lost. This may be a result of
+[MacRuby Ticket #1369](http://www.macruby.org/trac/ticket/1369), but
+it might also be because of
+[MacRuby Ticket #1320](http://www.macruby.org/trac/ticket/1320) or
+some other freedom patch
+that AXElements or ActiveSupport adds to the run time. I have not been
+able to create a reduction of the problem yet.
+
+The real problem is that loss of back trace happens for multiple
+exception classes. The [work around](https://gist.github.com/1107314)
+for this case is copied to `lib/ax_elements/macruby_extensions.rb`,
+but has been commented out since it causes some regression tests to
+fail. If you do not get a back trace with an error then you will need
+to uncomment the freedom patches or copy them to your own script.
+
+## Disabling Compiled Code
+
+Back traces can be lost for reasons other than a bug. When using
+compiled MacRuby code, you cannot get a Ruby level back trace in case
+of an error. This feature is on the road map for MacRuby, but I am not
+sure when it will be done.
+
+In the mean time, if you suspect that the portion of a back trace that
+would come from a compiled file is the problem, then you can disable
+loading compiled files which will force MacRuby to load source ruby
+files instead. You can disable loading compiled files by setting the
+`VM_DISABLE_RBO` environment variable before running a script. You can
+disable loading for a single session like so:
+
+    VM_DISABLE_RBO=1 macruby my_script.rb
+
+Other debugging options are also available from MacRuby itself. You
+should check out [Hacking.rdoc](https://github.com/MacRuby/MacRuby/blob/master/HACKING.rdoc)
+in the MacRuby source repository for more details.
+
+## Logging
+
+The core level of AXElements has logging in every case that an error
+code is returned. Though, it can show false positives because of
+hiccups in the accessibility API or implementation that an app
+provides; so it turned off by default. This feature is also going away
+in favour of more intelligent error handling in the core wrapper.
+
+When weird bugs are occuring, possibly even crashing MacRuby, you
+should try turning on the logs and then trying the script again. You
+might see some tell tale logs printed out right before the crash. You
+can turn on logging right after you load AXElements, like so:
+
+    require 'ax_elements'
+    Accessibility.log.level = Logger::DEBUG
+
+The standard log levels are available, the full set is available
+[here](http://rdoc.info/stdlib/logger/1.9.2/Logger/Severity). `Logger::DEBUG`
+will turn on all logs.
+
+## MacRuby Seems Slow
+
+There are a few things that can cause MacRuby to be slow. At boot time
+there are a number of factors, which I will cover, and at run time
+there is really only one culprit.
+
+### Long Load Times
+
+When using certain gems, or when you have many gems installed, you
+will notice that the load time for your scripts is very
+long---possibly more than 10 seconds. There are many reasons why this
+happens, some of which we can fix ourselves and some of which you will
+have to wait for the MacRuby developers to fix.
+
+#### Huge Literal Collections
+
+Some gems contain source code with
+[unbelievably large literal collections](https://github.com/sporkmonger/addressable/blob/master/lib/addressable/idna/pure.rb#L318),
+such as the `addressable` gem. This is a problem for MacRuby for two
+reasons.
+
+First, it requires several thousand allocations at once. Most of
+MacRuby's performance issues come from code that allocates too much,
+and large collections can allocate several thousand objects all at
+once.
+
+The second problem is that MacRuby normally will try to JIT the code,
+and the LLVM chokes on things this large. Some work has been done to
+break the function up into smaller pieces (it used to take over 2
+minutes to load the `addressable` gem), but it can still take a while
+for MacRuby and the LLVM to work through the code
+
+As it turns out, JIT isn't that great for short lived processes that
+need to start up over and over again. In fact, JIT mode for MacRuby
+was meant more for debugging.
+
+The work around to this situation will have to come from upstream gem
+developers and MacRuby itself. In the mean time, compiling these gems
+will usually make them load _significantly_ faster. To compile gems,
+you can install the
+[`rubygems-compile`](https://github.com/ferrous26/rubygems-compile)
+plug-in for rubygems. Follow the instructions from the plug-ins `README`
+to learn how to use it and to know which version to install.
+
+#### Complex Metaprogramming
+
+Another problem that can cause long load times is complex
+metaprogramming. Gems such as `rspec` do a lot of weird stuff at boot
+that causes the MacRuby optimizer to do a lot of work. `rspec` alone
+can add nearly 10 seconds to boot time. In this case you can tell the
+optimizer to not try so hard; this will result in slower run time
+performance, but it is likely worth the trade off in the case of
+`rspec` (unless you compile).
+
+You can set the optimization level for MacRuby just as you would
+disable loading compiled code:
+
+    # set the level to a number between 0 and 3, 3 is the highest
+    VM_OPT_LEVEL=1 macruby my_script.rb
+
+#### Large Code Bases
+
+Large code bases taking a long time to load is not really an avoidable
+situation---it happens with every project. Once again, JIT and
+optimizer passes take up a lot of the load time.
+
+In this case, it is best to compile your code (and test the compiled
+version) in order to speed up boot time. You can combine compiled code
+and still turn off optimization passes to get even better boot times,
+but I am not sure it is worth the trade off at that point.
+
+#### Rubygems
+
+Rubygems suffers from a lot of technical debt. The process of
+activating a gem incurs so many allocations that with as few as 25
+installed gems can add an extra 2 seconds to your boot time. What is
+worse, the performance degrades exponentially as you install more
+gems.
+
+The only fix for this is to cleanup and fix rubygems. Fortunately this
+has been underway since the rubygems 1.4; the downside is that MacRuby
+has customizations to rubygems that prevent users from upgrading
+themselves. We need to wait for new MacRuby releases to bundle new
+rubygems versions in order to fix this issue.
+
+### Slow Runtime Performance
+
+In my experience, slow runtime performance in MacRuby is almost always
+the result of many allocations. If your code is runinng abnormally
+slow then it is likely that you are allocating a lot of memory without
+realizing it, and you should compare performance to CRuby if it is
+important (and if it is possible to run the code on CRuby).
+
+Remember that things like literal strings have to be copied every time
+the line of code they are on is run, whereas immutable things like
+symbols do not have to be copied. At the same time, if you pass a
+symbol to a method that will coerce the symbol to a string then you
+haven't saved an allocation.
+
+Try to use in-place mutations when it is safe. An example would be
+when you have to perform multiple changes to an object in a single
+method, you only have to create a new copy the first time and then use
+the same copy for all the other changes. Example code would look like this:
+
+    def transform string
+      new_string = string.gsub /pie/, 'cake'
+      new_string.gsub! /hate/, 'love'
+      new_string.upcase!
+      new_string
+    end
+
+Remember that built-in in-place methods tend to return `nil` if they
+don't make any changes, which means you need to explicitly return the
+new object at the end of the method. There are still many other easily
+avoidable cases where you could end up allocating a lot of memory
+which are not covered. If it is important you willl just have to
+analyze your code.
+
+Sometimes allocating a lot of memory is not avoidable; running RSpec
+would be an example of this. In these cases you just have to bite the
+bullet.
+
+## Don't Be Afraid To Log Bugs
+
+Or look at the AXElements source code for that matter. The source is
+well documented and hopefully not too clever, so it shouldn't be too
+hard to figure things out. You can log AXElements bugs on Github where
+the source is being hosted.
+
+Though, sometimes the problem will be a MacRuby problem and the best
+way to get it fixed is to
+[log a bug](http://www.macruby.org/trac/). You will need to create an
+account with them to log bugs.
+
+I also recommend that you subscribe to the
+[MacRuby mailing list](http://lists.macosforge.org/mailman/listinfo.cgi/macruby-devel)
+to keep up to date on MacRuby developments. You can send in questions
+if you are unsure about a certain behaviour, even potential bugs. It
+is not a high traffic mailing list so it won't blow up your mailbox
+when you subscribe.