OData

I was asked how to setup the SampleService used for integration testing the ruby_odata library (with Cucumber). If you’re not familiar with ruby_odata, it is a RubyGem used to communicate with OData services through Ruby. I’m happy to say that it’s been used in some rather large projects. The ruby_odata project contains tests that run in isolation (unit tests and acceptance tests), but there are also full integration tests that work against a “SampleService.” This service needs to run on Windows, and a lot of developers, including myself, use Linux or OS X as their development machine. In order to fully test ruby_odata, we’ll set up a virtual machine using VirtualBox and run the SampleService from there.

Initial Steps

I’m not going to bore you with the installation details of Windows, as I’m sure you’ve installed it before. I’m going to be installing Windows 8.1 Pro on a VirtualBox machine with 4GB of RAM. You can of course use another version of Windows, like Windows 7, but I figured I’d go with the latest release for this example. Once you have Windows installed, be sure to install the VirtualBox Guest OS Additions. Once you install the additions, make sure you reboot the virtual machine.

Figure 01: VirtualBox Guest Additions
Figure 01: VirtualBox Guest Additions

Getting the SampleService Up and Running

The quickest way to get your Virtual Machine set up involves first installing Rails Installer. This will get you Git and Ruby complete with the DevKit to build native C-based RubyGems. Once the install finishes, you should set up Git with your name and email address.

You will also need IIS Express, which you can get by installing Microsoft WebMatrix.

Finally, you will want to clone the ruby_odata project from GitHub.

    git clone https://github.com/visoft/ruby_odata.git

You want to run this command in a development directory. I made a new directory Development under my User folder (e.g. C:\Users\dwhite\Development). Once those steps are completed, open a command prompt and change into the directory \ruby_odata\test. From there, run the appropriate iisExpress batch file. If you are on an x64 system like I am, you’d run iisExpress x64.bat, otherwise use iisExpress x86.bat. If all goes well, you should see the following output.

Replacing Configuration Data
Starting IIS Express ...
Successfully registered URL "http://localhost:8989/" for site "ruby_odata test site" application "/"
Successfully registered URL "https://localhost:44300/" for site "ruby_odata test site" application "/"
Successfully registered URL "http://localhost:8989/SampleService/" for site "ruby_odata test site" application "/SampleService"
Successfully registered URL "https://localhost:44300/SampleService/" for site "ruby_odata test site" application "/SampleService"
Registration completed for site "ruby_odata test site"
IIS Express is running.
Enter 'Q' to stop IIS Express

Open up your web browser on the Virtual Machine and attempt to hit the URL http://localhost:8989/SampleService/RubyOData.svc/, if all worked correctly, you’ll see the collections available to you (Products, Categories, etc.).

Figure 02: Collections Available
Figure 02: Collections Available

Once you confirm that everything is working locally (on the guest machine) stop IIS Express by typing the letter Q to quit.

Hitting the SampleService From Your Host Machine

We currently can just use SampleService from the localhost (the guest machine). I want to be able to use my Mac to work with Ruby and have it connect to the SampleService running on the guest machine. Enabling this is fairly painless thanks to configuration variables used in ruby_odata. Our first step is changing our Virtual Machine’s network configuration from NAT to Bridged Adapter. You do this by clicking on the network icon in VirtualBox and choosing Network Settings.

Figure 03: Bridged Adapter
Figure 03: Bridged Adapter

Now, let’s grab the IP address of the guest machine. You can do this by running the command ipconfig in Windows. This should look like other addresses on your network because it’s now grabbing that value from your DHCP server. For stability, you may want to assign a fixed IP to this virtual machine. This will ensure the IP address doesn’t change on you.

Now, armed with the IP address, we need to set an environment variable, ODATA_SERVER. You can also set different ports if you’d like. The defaults are 8989 for standard HTTP, and 44300 for HTTPS. These variables are ODATA_PORT and ODATA_SSL_PORT. To set an environment variable in Windows, go to System, then Advanced system settings, finally Environment Variables…. Add a User variable for ODATA_SERVER with your IP address. If you wish to change the ports, you can add variables for those listed above as well. When you are all set, hit OK.

Figure 04: Environment Variables in Windows
Figure 04: Environment Variables in Windows

Serving the Service

Since we’re now using an IP address for IIS Express, you need to make sure your cmd prompt is running as Administrator, otherwise during the next step, you’ll get a bunch of Access Denied errors. Before you run IIS Express though you need to open ports in the Windows Firewall, or just turn the Windows Firewall off :). With that out of our way, open up a cmd prompt as Administrator, change into ruby_odata\test and run the appropriate iisExpress batch file. Now for the real test. On your host machine, open your browser and attempt to connect to http://<YOUR HOST'S IP ADDRESS>:8989/SampleService/RubyOData.svc/. If all has gone well, you should see the list of collections again. Be sure also to check the SSL version of the service at `https://<YOUR HOST’S IP ADDRESS>:44300/SampleService/RubyOData.svc/’.

Setting Up Your Host Machine

Now, in order to run the Cucumber tests, you’ll need to set (at a minimum) the ODATA_SERVER environment variable on the machine where you are running the tests. On my system, I use oh-my-zsh, so I set my variable in my .zshrc file, but if you use bash, it should be similar.

export ODATA_SERVER=192.168.1.125

Now you can go ahead and run the Cucumber tests and record new VCR cassettes by changing features\support\vcr to :record => :all. Just be sure to set this back to :none when you are done so that Travis-CI can run the Cucumber features without the SampleService.

Conclusion

I hope this helps in setting up your system to make changes to ruby_odata. Unfortunately, I haven’t done too much with further development, but I’d like that to change. Your pull-requests fuel me to do more. If you use ruby_odata, I’d love to hear from you. Also, if you need any additional help setting up your Virtual Server or have any ruby_odata questions, don’t hesitate to contact me.