Integration Testing ASP.NET MVC Projects with SpecsFor.Mvc

SpecsFor.Mvc

I’ve recently spent some time looking into different frameworks for doing integration testing for ASP.NET MVC projects. One that caught my eye almost immediately was SpecsFor.Mvc. Unlike other solutions I found for writing integration tests, SpecsFor.Mvc lets you write tests in a fashion that is very similar to writing unit tests, using strongly-typed access to your application’s data without having to script or dig into the DOM.

Some nice things that SpecsFor.Mvc provides out-of-the-box:

  • Hosts your ASP.NET MVC project, building a specified configuration of your project and then hosting it automatically under an instance of IIS Express
  • Provides strongly-typed methods for navigating to controllers and actions, checking route results, and filling out and submitting forms
  • Provides access to validation data, including access to the validation summary as well as the validity of each property in your view’s model

SpecsFor.Mvc uses Selenium WebDriver internally in order to drive the browser. You can still access the Selenium IWebDriver interface any time you need to dig further into your page.

Let’s take a look at these things in practice by writing a few hypothetical tests written against the stock ASP.NET MVC Internet Application.

Starting the Project

To get started, create a new ASP.NET MVC 4 project in Visual Studio.

New ASP.NET MVC 4 Web Application

Select the Internet Application project template, check the option to create a unit test project and click OK.

Internet Application Project Template

Once both the ASP.NET MVC project and the unit test project have been created, right-click the References folder under your Tests project and click Manage Nuget Packages.

Manage Nuget packages

Under Online, search for and install the official SpecsFor.Mvc Nuget package.

SpecsFor.Mvc Nuget Package

Initializing the Hosting Environment

The next thing that we need to add to the Tests project is some code that will initialize the IIS Express hosting environment using the classes provided by SpecsFor.Mvc. To do this, create a new class called MvcAppConfig with the following contents (adjust the namespace as needed):

using Microsoft.VisualStudio.TestTools.UnitTesting;
using SpecsFor.Mvc;

namespace SpecsForMvcDemo2.IntegrationTests
{
    [TestClass]
    class MvcAppConfig
    {
        private static SpecsForIntegrationHost integrationHost;

        [AssemblyInitialize()]
        public static void MyAssemblyInitialize(TestContext testContext)
        {
            var config = new SpecsForMvcConfig();

            config.UseIISExpress()
                .With(Project.Named("SpecsForMvcDemo"))
                .ApplyWebConfigTransformForConfig("Debug");

            config.BuildRoutesUsing(r => RouteConfig.RegisterRoutes(r));

            config.UseBrowser(BrowserDriver.Chrome);

            integrationHost = new SpecsForIntegrationHost(config);
            integrationHost.Start();
        }

        [AssemblyCleanup()]
        public static void MyAssemblyCleanup()
        {
            integrationHost.Shutdown();
        }
    }
}

The class is marked as a TestClass even though there are no explicit methods to test. This is so that the MyAssemblyInitialize() and MyAssemblyCleanup() methods run. In order for the AssemblyInitialize and AssemblyCleanup attributes to work the class must be marked with the TestClass attribute. With this code in place, MyAssemblyInitialize() will run once before all of the test methods in the project and MyAssemblyCleanup() will run after they all complete.

The code found in MyAssemblyInitialize() is fairly straight-forward given the clarity of the SpecsFor.Mvc API. A new SpecsForMvcConfig instance is created and set to use IIS Express with a given project name and configuration name. Next, a call to BuildRoutesUsing is made in order to register the various controllers and actions with SpecsFor.Mvc. Finally, the browser is specified and the configuration is used to start a new instance of the SpecsForIntegrationHost.

The MyAssemblyCleanup() method, paired with the AssemblyCleanup attribute, is used to shut down the integration host after all the tests have completed.

Initializing the Browser

Now that we have code in place to host the ASP.NET MVC site before any tests are run, we need some code in place to create an instance of our MVC application in a browser. Right-click the Tests project and add a new Unit Test.

Add Unit Test

Add the following code to the top of your new UnitTest1 class, before the TestMethod1 declaration:

private static MvcWebApp app;

[ClassInitialize]
public static void MyClassInitialize(TestContext testContext)
{
    //arrange
    app = new MvcWebApp();
}

This will require adding a using statement for SpecsFor.Mvc.

Using SpecsFor.Mvc

This new method, MyClassInitialize() will run before all of the tests in the new UnitTest1 class. It will create a new instance of the MvcWebApp class which will launch the browser with your application loaded.

If you go ahead and run the tests for UnitTest1 now you’ll see that two console windows are opened, one for IIS Express hosting the ASP.NET application and one for the Selenium WebDriver that is driving your application. In addition, after the Selenium WebDriver console window is opened, the browser specified in the MvcAppConfig class will be launched.

Note that you may get a prompt from Windows Firewall that you’ll need to allow.

Firewall Alert

Because we haven’t actually written any tests yet, all these windows will close after they are opened, but this demonstrates that these few lines of code used to bootstrap the environment are working.

Authentication Tests

Now that all the setup work is done, let’s see what some actual integration tests look like using SpecsFor.Mvc. The first test will ensure that, if a user tries to navigate to the /account/manage route of the ASP.NET MVC application without logging in, they will be redirected to the login screen.

[TestMethod]
public void AccountManage_WithoutSession_RedirectsToLogin()
{
    //act
    AccountController.ManageMessageId? messageId = null;
    app.NavigateTo<AccountController>(c => c.Manage(messageId));

    //assert
    const string returnUrl = "%2fAccount%2fManage";
    app.Route.ShouldMapTo<AccountController>(c => c.Login(returnUrl));
}

This test will require adding two new items to the using statements: YourProjectName.Controllers and MvcContrib.TestHelper (MvcContrib.TestHelper is needed for the call to ShouldMapTo).

And that’s it for the first integration test. I love it. It’s clear, concise, and (aside from the return URL path) it’s strongly typed. The call to NavigateTo will navigate to the URL corresponding to the AccountController and the Manage action, specified in the lambda expression. The call to ShouldMapTo will ensure that the resulting route corresponds to the AccountController and Login action (with the proper ReturnUrl parameter).

Let’s add two more tests to illustrate a few more examples using SpecsFor.Mvc:

[TestMethod]
public void Login_InvalidInput_TriggersValidation()
{
    //act
    app.NavigateTo<AccountController>(c => c.Login(string.Empty));
    app.FindFormFor<LoginModel>()
        .Field(f => f.UserName).SetValueTo(string.Empty)
        .Field(f => f.Password).SetValueTo(string.Empty)
        .Submit();

    //assert
    app.FindFormFor<LoginModel>()
        .Field(f => f.UserName).ShouldBeInvalid();
    app.FindFormFor<LoginModel>()
        .Field(f => f.Password).ShouldBeInvalid();
}

[TestMethod]
public void Login_InvalidCredentials_TriggersValidation()
{
    //act
    app.NavigateTo<AccountController>(c => c.Login(string.Empty));
    app.FindFormFor<LoginModel>()
        .Field(f => f.UserName).SetValueTo(Guid.NewGuid().ToString())
        .Field(f => f.Password).SetValueTo(Guid.NewGuid().ToString())
        .Submit();

    //assert
    app.ValidationSummary.Text.AssertStringContains("incorrect");
}

These tests will require adding a using statement for YourProjectName.Models so that the LoginModel class can be accessed.

Again, looking at the code, I love the simplicity and clarity in the SpecsFor.Mvc tests. I can use NavigateTo to navigate to my controller and action, and then use FindFormFor to access my view’s model. Finally I can submit the form with easy access to the resulting validation data.

Unfortunately, if you try to run these new tests right now they will fail. The reason is that the SpecsFor.Mvc initialization code compiles and deploys a fresh copy of the ASP.NET MVC project to a TestSite folder within the Debug folder. The App_Data folder contents are not included in the ASP.NET MVC Visual Studio project. So, the database files are not deployed to the TestSite folder and the site itself will YSOD if you try to do anything requiring the database.

No DB YSOD

To fix this, right-click the App_Data folder in your main MVC project and click Add>Existing Item.

Add Existing Item

Then, add the two files found in your physical App_Data folder to the project (you’ll need to run the MVC site and access the database once manually).

After adding the MDF and LDF files to the project you should be able to run all of the authentication integration tests without error.

The Big But

Pee-Wee Big But

Now this all sounds great, but

At the time I’m writing this, SpecsFor.Mvc tests run great under third-party test runners such as TestDriven.Net and CodeRush. However, the tests don’t run under Visual Studio’s MSTest runner. Trying to run the tests using Visual Studio’s built in test runner will result in a “Build failed” error. The author of SpecsFor.Mvc has reproduced the issue and is hoping to have it fixed within a couple of days.

UPDATE: This issue has since been resolved by Matt and is no longer a problem in version 2.4.0. No more buts!

Resources

Bitcoin & Litecoin Proxy Mining on Mac OS X

Bitcoin

When it comes to mining Bitcoins and Litecoins there are two major protocols involved: the older Getwork protocol and the newer Stratum protocol. At this point the Stratum protocol has all-but-replaced the Getwork protocol. All major mining pools and mining software support Stratum and Getwork is deprecated.

This is usually not a problem, however some older mining utilities (for example the Litecoin CPU miner) do not have Stratum support. And some pools, such as Slush’s Bitcoin pool or WeMineLTC, have limited-to-no support for Getwork. This is where a very nice Python utility called the Stratum Mining Proxy can help.

You can use the Stratum Mining Proxy on any computer to connect to your desired Bitcoin or Litecoin pool. Then you can connect your mining software to the IP address of the computer the proxy mining software is running on. All of the Getwork network requests from the mining software will be reshaped into the Stratum protocol and then forwarded on to the mining pool.

Installing the Xcode Command Line Tools

In order to install the mining proxy you’ll need a set of command line utilities for compiling software. You have two options:

  1. Install Xcode for free from the App Store and then use Xcode to install the Command Line Tools package
  2. Install only the Command Line Tools package from an unofficial (non-Apple) source

If you would rather play it safe and stick to as many trusted sources as possible, or if you plan to make use of the Xcode IDE, go with the first option. If you’d rather save some disk space and don’t mind using a widely used – if unofficial – source, go with option two.

Option 1: Install Xcode and Command Line Tools

To get started using this option you will need to install the Xcode. Xcode is a free download from the Apple App Store.

Xcode on App Store

Next you’ll use Xcode to install the Command Line Tools. Launch Xcode and then click the Xcode>Preferences menu item. Click the Downloads tab and then click Install next to Command Line Tools.

Xcode Downloads

If the text next to Xcode Command Line Tools says Installed, carry on to the next step.

Option 2: Install just the Command Line Tools

If you would like to install only the GCC Command Line Tools you can download the package for your version of OS X here.

Standalone GCC Installer

Simply run the setup package after downloading and step through the installer.

Downloading the Mining Proxy

The original Stratum Mining Proxy project was created by Slush, who also runs one of the more popular mining pools and is very involved in the Bitcoin community and development, from proposing the concept of pooled mining to proposing the Stratum protocol.

However his original project is for Bitcoin miners and pools only. In order to support both Bitcoin and Litecoin mining you’ll want to refer to this fork which includes support for the scrypt algorithm used by Litecoin. You can either download the latest source as a zip file or use Git to clone the repository.

Installing Scrypt (Litecoin) Support

If you downloaded a zip file of the mining proxy source rather than using Git to clone the repository, extract the zip file contents by double-clicking.

Next, open Terminal.app from the Applications folder or using Spotlight. Use the cd command to navigate to the mining proxy source. For instance, if you downloaded the source as a zip file:

cd ~/Downloads/stratum-mining-proxy-master

Next, change directory to the Litecoin scrypt module:

cd litecoin_scrypt

Finally, install the scrypt module for Litecoin support:

sudo python setup.py install

Installing the Stratum Mining Proxy

Now, in the Terminal app window change the working directory back up to the root of the mining proxy source:

cd ..

And finally install the mining proxy:

sudo python setup.py install

Install Mining Proxy

Using the Mining Proxy

Once the mining proxy is installed, using it is fairly straight forward. Normally your Bitcoin or Litecoin miner connects to a host and port with a specific username and password. For instance:

minerd -o http://pool-host:pool-port -u pool-username -p pool-password -t thread-count

With the mining proxy you’ll want to first run the proxy itself, connecting to the pool’s host and port:

mining_proxy.py -nm -o pool-host -p pool-port

If you are mining Litecoins, use the -pa parameter:

mining_proxy.py -nm -pa scrypt -o pool-host -p pool-port

Mining Proxy Output

Then run your miner, but specify your computer’s IP address and the port number reported by the mining proxy output:

minerd -o http://your-ip:port-from-output -u pool-username -p pool-password -t thread-count

Mining Proxy Output - Clients

Other Benefits

There are a couple of other benefits of the Stratum Mining Proxy that are worth noting:

  1. The mining proxy supports both Getwork and Stratum clients. This means you can use the proxy to consolidate network traffic regardless of the mining protocol.
  2. Using the mining proxy gives you a simple way to get a heads-up view of which machines are alive and which are submitting accepted work by referring to the Terminal output.

Resources

To learn more about mining Bitcoins and Litecoins on OS X, see my previous blog posts:

Bitcoin Mining – Part 1
Bitcoin Mining – Part 2
Bitcoin Mining – Part 3
Litecoin Mining – Part 1
Litecoin Mining – Part 2

Litecoin Mining on Mac OS X – GPU Mining

Litecoin Logo

My previous article on Litecoin mining I discussed how you can get started mining Litecoins, an alternative to the Bitcoin crypto-currency, using your spare CPU cycles. If you’re GPU is already mining Bitcoins, using your CPU to mine Litecoins may be an obvious choice. However, if you are “all in” on Litecoin then you can get a sizable performance increase by using your GPU to mine Litecoins. Whether that trade-off is worth-while is a decision you would need to make. Litecoin is not as mature as Bitcoin and is just as volatile. Some see it as a doomed clone, others as the next Bitcoin, poised to take off.

GPU Mining

In order to start using your GPU to mine Litecoins on OS X, you’ll need to first install cgminer or bfgminer. Please read my previous article on Bitcoin mining for step-by-step instructions and installation packages for cgminer and bfgminer. The Homebrew formulas I shared in my previous article include the configuration settings necessary to mine both Bitcoins and Litecoins. If you are compiling the applications yourself, make sure to use the –enable-scrypt parameter when running ./configure.

Armed with a copy of cgminer or bfgminer with scrypt enabled, you can now start mining Litecoins with your GPU. Now a fair warning: finding a nice set of parameters for mining Litecoins with cgminer or bfgminer is far more finicky and time consuming. With Bitcoins you can basically run either miner and just specify your pool. The miner will then tune itself and eventually reach a nice hash-rate.

This isn’t really the case with using either miner to mine Litecoins. For instance, if I use the following command line to mine Litecoins using my ATI 5770. Note that I am using the -d parameter to specify which GPU to use to simplify these examples.

cgminer --scrypt -o host:port -u username -p password -d 0

cgminer No Params

With no additional tuning my 5770 gets about 5Kh/s. My CPU alone gets around 29Kh/s. Using bfgminer with the basic command-line parameters yields similar results. As indicated in my previous article I use the –no-opencl-binaries to work around a crash in bfgminer with multiple GPU’s on OS X.

bfgminer --scrypt -o host:port -u username -p password -d 0 --no-opencl-binaries

bfgminer No Params

So how can we get better performance mining Litecoins on the GPU? The first parameter to focus on is the -I parameter, or the intensity. With Bitcoin this parameter does help, but honestly not a ton. If you aren’t using the PC, and you leave the intensity at “Desktop” (-I d), both cgminer and bfgminer will eventually reach around the same performance you’d get by specifying something like -I 9.

This is not the case with Litecoin mining. With scrypt (Litecoin’s hashing algorithm) you need to specify a high intensity, in fact higher than is suggested for Bitcoin. I’d start at around 10 and go up from there. On my system, 15-16 is about the best I can do.

So lets try cgminer with -I 13 to see what that does:

cgminer --scrypt -o host:port -u username -p password -d 0 -I 13

cgminer with I

That change alone triples the Kh/s, but from 5Kh/s to 15Kh/s honestly isn’t much to brag about. Let’s try with bfgminer:

bfgminer --scrypt -o host:port -u username -p password -d 0 --no-opencl-binaries -I 13

bfgminer with I

Similarly I get around 14Kh/s using the -I 13 parameter with bfgminer.

The next parameter to focus on is the -w parameter, which specifies a worksize in multiples of 64 up to 256. This parameter is what really makes a difference on my OS X rig:

cgminer --scrypt -o host:port -u username -p password -d 0 -I 13 -w 64

cgminer with I w

Now we’re cooking with Crisco! Using -I 13 -w 64 on my 5770 gets me from the original 5Kh/s up to 83Kh/s with cgminer. And with bfgminer?

bfgminer --scrypt -o host:port -u username -p password -d 0 --no-opencl-binaries -I 13 -w 64

bfgminer with I w

This gets us up to around 80 Kh/s with bfgminer as well. By removing the -d parameter so that both GPU’s are used and cranking up the -I parameter to 16 I can get my GPU’s up to around 230 Kh/s:

cgminer --scrypt -o host:port -u username -p password -I 16 -w 64

cgminer Two GPUs

The last parameter I want to note is –thread-concurrency. If cgminer or bfgminer are reporting hardware errors (the HW number in the output) this indicates that you need to make use of the –thread-concurrency parameter. These are not hardware failures. You can find guidelines for the value to use here:

57xx cards: 2368-4096 (3200 is common)
58xx cards: 4096-8192 (5600, 7168, and 8000 are common)
5970 cards: 4096-8192 (5632 or 8000 are common)

67xx cards: 2368-4096 (3200 is common)
68xx cards: 3008-6720 (4800 is common)
69xx cards: 4096-8192 (5600, 7168, and 8000 are common)
6990 cards: 4096-8192 (5632 or 8000 are common)

7xxx cards: 64 * bus-width-of-card-in-bits. So, for a 7950, that would be 64 * 384 = 24576. Ideal values are 21712 or 24000. Find your bus width here.

I verified that 3200 works well with a 5770 and 4800 works well with a 6870.

Conclusion

And that about covers it for my series of articles on mining Bitcoins and Litecoins using Mac OS X and Apple hardware. The growing landscape of crypto-currency is fascinating from many perspectives. If your interest is piqued and you are running OS X, hopefully you now have the information you need in order to get started mining this new form of currency.

Litecoin Mining on Mac OS X – CPU Mining

Litecoin Logo

My previous series of articles on crypto-currency covered Bitcoin mining on OS X. This series will focus on mining Litecoins. While Bitcoin has been getting the lion’s share of media attention lately with its recent bubbles and crashes and growing adoption, Litecoin has been slowly growing in popularity among alternative crypto-currencies (known as altcoins).

What is Litecoin you may ask? Litecoin is a fork of the Bitcoin project with three important changes:

  1. The hashing algorithm uses is Scrypt rather than SHA-256
  2. Blocks are approved four times faster than Bitcoin blocks
  3. Litecoin is setup to produce 84 million Litecoins, versus Bitcoin’s 21 million target

Proponents of Litecoin argue that Litecoin should be regarded as silver to Bitcoin’s gold: easier and faster to transact smaller amounts. Proponents also argue that, by basing the proof-of-work on Scrypt rather than SHA-256, Litecoin mining will remain in the realm of consumer hardware, rather than limited to mining-specific hardware (like Bitcoin with FPGA’s and ASIC’s). While SHA-256 benefits from massive, parallel processing, Scrypt is built to be very memory-intensive. This means that, for the time being, mining Litecoins using your CPU (which is no longer profitable with Bitcoin) is still possible. You can also use your GPU to mine Litecoins, which gives me a 5x performance boost over CPU mining.

One popular setup seems to be using your GPU’s to mine Bitcoins and use spare CPU power to mine Litecoins. This article will cover how you can use Mac OS X to mine Litecoins using your CPU. If you’re interested in harnessing your GPU’s power to mine Litecoins rather than Bitcoins, a future article will cover that topic.

CPU Mining

To get started with Litecoin mining on OS X, download the official Litecoin wallet application – Litecoin-QT – from the Litecoin website. With the Litecoin wallet you can actually mine from within the UI. Download the DMG file and drag the Litecoin-QT app to your Applications folder.

Litecoin QT DMG

Now, I didn’t cover wallet setup in my Bitcoin series as it was outside the scope of mining. However, as Litecoin CPU mining is generally done within the wallet application (though it can be done at the command-line), I want to make two things clear. First, encrypt your wallet. Second, double-check that the encryption phrase you’ve recorded is correct and works before you start making deposits. The same thing goes for your Bitcoin wallet.

As stated above, the Litecoin wallet UI is capable of showing and controlling mining. While the Litecoin wallet has built in support for solo mining, pooled mining requires another download (see my first article for a brief overview of mining pools). The download is from a project called cpuminer. The cpuminer project was originally a CPU miner for both Bitcoin and then for Litecoin, when CPU mining for Bitcoin was still sensible. These days it’s been replaced in the Bitcoin world by cgminer and bfgminer, and is used in the Litecoin world for CPU mining. You can download the OS X binary for this cpuminer fork directly from the project’s GitHub downloads (32-bit, 64-bit).

Once you’ve downloaded and extracted the cpuminer binary, called minerd, place it alongside the Litecoin-QT app in your Applications folder. This makes it possible to use the pooled miner from within the Litecoin wallet.

UPDATE: The Mining tab has been removed from the Lightcoin-QT wallet. Skip down a couple of paragraphs for details on mining from the command-line.

Now you’re ready to start mining. Switch to the Mining tab in Litecoin-QT. Change the Type to Pool Mining. Set the Threads value to the number of cores you have (double that if you have Hyper-threading). You can leave the Scantime value. It is only used if the mining pool doesn’t support long-polling, which is rarely the case these days. For the Server, Port, Username and Password, enter your mining pool information. Using P2Pool mining pools is fairly popular with Litecoin. You can use p2pool.org or any number of alternatives.

Once you’ve got your mining pool information filled in, click Start Mining to get started.

Litecoin QT Mining

The Litecoin-QT UI will display the output from minerd and a running total of accepted and rejected shares, as well as average hashes-per-second.

Command-Line Mining

Now, if you’re the kind of gal (or guy) who prefers to do your work at the command-line, it’s not required that you use the Litecoin wallet app. While mining from within the app is nice as it gives you running totals, you can just as easily mine from the command-line with the following command:

./minerd -o http://host:port -u username -p password -t thread-count

Command Line LTC Mining

What’s Next?

In the follow-up to this article I’ll discuss the utilities, steps, and tweaks necessary to mine Litecoins on OS X using your GPU. While this doesn’t give the same magnitude of increased performance found when mining Bitcoins on the GPU versus CPU, the increase is still enough to make GPU’s the preferred way of Litecoin mining. However, that also means dedicating GPU cycles to Litecoins rather than Bitcoins, which is a decision you’ll have to make. Litecoins aren’t nearly as established as Bitcoins, so they could be poised to gain in value like Bitcoin has. At the time of this post they trade at around $4 versus Bitcoin hovering around $125). Others call into question Litecoin’s benefits over Bitcoin, seeing it as a doomed clone.

Only time will tell.

UPDATE: If you need to connect the CPU miner to a pool that doesn’t support Getwork, have a look at this post for a solution.

Bitcoin Mining on Mac OS X – cgminer & bfgminer

Bitcoin

In my previous two posts in this series I introduced two easy-to-use bitcoin miners for OS X: BitMinter and GUIMiner. However, while these miners are relatively easy to install and use, they do not offer the best performance when it comes to hash rates. For that you’ll want to look at cgminer and bfgminer. These are native C miners and, paired with the right kernels, their performance exceeds the other two miners by quite a wide margin.

cgminer & bfgminer

The bfgminer project is a fork of the cgminer project. Now, I have no dog in this fight, but my understanding is that the teams aren’t on great terms. However, I have had good luck with both tools and have worked with both authors in order to fix a crash (cgminer, bfgminer) related to multiple GPU’s on OS X and have no complaints whatsoever. Both miners offer similar performance in my experience.

Installation

1. Xcode
To get started, you will need to install the Xcode. Xcode is a free download from the Apple App Store.

Xcode on App Store

2. Command Line Tools
Next you’ll need the Xcode Command Line Tools. Launch Xcode and then click the Xcode>Preferences menu item. Click the Downloads tab and then click Install next to Command Line Tools.

Xcode Downloads

If the text next to Xcode Command Line Tools says Installed, carry on to the next step.

3. Homebrew
Next you’ll need to install Homebrew. Homebrew is a package manager for OS X that provides a sane way of installing *nix tools, libraries, and their dependencies. It is similar to MacPorts for OS X or apt for Linux. Installing Homebrew is super-easy. Open up Terminal.app and run the following command (from the Homebrew homepage):

ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

After you install Homebrew, make sure you run the following command (as the installer should instruct you):

brew doctor

Make sure you address any errors or warnings before proceeding as they may prevent the miners from installing.

4. Miners
In my previous post I indicated that it was necessary to compile cgminer and bfgminer from their source code in order to install them on OS X. While that was necessary at the time, after some reading and experimenting with Homebrew I was able to create packages (called formulas with Homebrew) for installing cgminer and bfgminer on OS X 10.8. Once Homebrew is successfully installed, you can run the following commands to install cgminer and bfgminer:

brew tap nwoolls/xgminer
brew install cgminer

or:
brew tap nwoolls/xgminer
brew install bfgminer

If you specify the –HEAD (two dashes) parameter for brew install then the latest source-code will be pulled for the miner from Github rather than using the latest official release.

You can visit the Github repository to view the package contents.

If you run into errors installing the above formulas you can try running brew install with the –debug –verbose parameters to find where things went wrong. I’d also recommend using brew doctor to diagnose any issues.

Usage

Both cgminer and bfgminer are command-line utilities. You can either run them without any command line parameters and fill in the prompts for mining pool URL and credentials or you can use the following format to specify your pool:

cgminer -o http://pool.url:port -u username -p password

or:
bfgminer -o http://pool.url:port -u password -p password

If you have multiple graphics cards you’ll want to use the –no-opencl-binaries parameter with bfgminer to avoid a crash on startup. This is not necessary with cgminer as it detects OS X and applies the same workaround automatically.

Other notable command line parameters are -I (for intensity) and -k (for kernel). If you pass in -I d then the miner will use less resources so you can use your PC (think D for Desktop). Passing in -I 9 is a safe value for having the miner use as much of your graphics resources as possible to mine. Your PC will be much less responsive. Finally, -k lets you specify a kernel. I find on OS X that using -k diablo gives the best performance. So, my command-line using cgminer with the BitMinter pool would look something like this:

cgminer -k diablo -o http://mint.bitminter.com:8332 -u username_workername -p password -I 9

cgminer Hashing

And for bfgminer:

bfgminer -k diablo -o http://mint.bitminter.com:8332 -u username_workername -p password -I 9 --no-opencl-binaries

bfgminer Hashing

Refer to the projects on Github for full documentation of the available command-line parameters.

As you can see from the average in the upper-left of each miner’s output, with cgminer and bfgminer I average 460 Mh/s. Compare that to 400 Mh/s with GUIMiner and 370 Mh/s with BitMinter and you can see why these command-line miners are preferred over their GUI counterparts.

Conclusion

These are exciting times for crypto currency, whether you’re a geek or a speculator or merely a bystander. And, while OS X is pulling up the rear when it comes to supported OS’s for bitcoin mining, hopefully I’ve demonstrated some viable options for getting your feet wet with mining on OS X. BitMinter is a great option for getting started, as it gives you both a bitcoin mining pool with low fees and ready-to-use mining software. GUIMiner is a nice option for improved performance and flexibility in mining pool choice. And, if you’ve decided mining is your thing and you want the absolute best performance out of your rig, you can’t go wrong with cgminer or bfgminer.

UPDATE: Since my original post I’ve had some great help from Bitcoin community member and blogger Kerry on how to get binaries such as cgminer and bfgminer packaged in a self-contained way. If you are interested in the shell scripts that make this possible you can check them out on Github here. I have submitted these scripts to the authors of both cgminer and bfgminer so, in the future, we may see official OS X binary distributions.

In the meantime, if you’d like to try these out instead of following the instructions above, you can download them from the Releases page here.

Bitcoin Mining on Mac OS X – GUIMiner

Bitcoin

In my previous post on bitcoin mining using Mac OS X, I discussed what is in my opinion the easiest way to get your toes wet with mining: BitMinter. BitMinter is a great bitcoin mining pool and its Java based miner makes it very simple to try out bitcoin mining on Mac OS X using your graphics card to calculate hashes.

And while I’m a fan of the BitMinter pool, the mining software – though easy to try – has two notable downsides:

  • The mining software only supports using BitMinter’s mining pool
  • The performance of the mining software falls behind alternatives such as GUIMiner, cgminer and bfgminer

GUIMiner

In terms of ease-of-use, the next bitcoin miner for OS X I’ll discuss is GUIMiner. GUIMiner is also available for Windows and, unfortunately, it’s much easier to find recent binaries for Windows than for OS X.

You can download the official OS X release of GUIMiner here. However, this release is a year or so old at the time of this post. You may be able to find more recent releases here, but you’d be trusting unofficial code on your system.

After you download the disk image (dmg) file, make sure you move the guiminer.app file to a writable location. Attempting to launch it from the dmg file directly will result in GUIMiner crashing.

GUIMiner Error

Once you launch GUIMiner, setup is straight-forward. You can click File>New to create a new tab for a miner. Only the OpenCL miner is supported out-of-the-box. After creating a new OpenCL miner tab, you can select a server (mining pool) from the drop down or select Other and enter the host, port, username and password manually. Select your device (graphics card) and finally click the Start mining! button.

GUIMiner 6870

If you have multiple graphics cards, you can add additional miners from the File>New menu or, if you plan on using the same mining pool, right-click your existing miner tab and click Duplicate.

Click View>Summary to get an overview and controls for each graphics card.

GUIMiner Summary

As you can see there is a noticeable performance improvement using GUIMiner and the poclbm kernel instead of BitMinter. With my own hardware I get a boost of about 30 Mh/s using GUIMiner instead of the BitMinter client.

So GUIMiner works well on OS X, with performance benefits and the ability to taget any bitcoin mining pool. However, it does have a couple of drawbacks:

  • The app doesn’t close properly – you must force quit the application
  • The performance still isn’t comparable to native C miners such as cgminer and bfgminer

In the final post in this series I’ll discuss these last two miners: cgminer and bfgminer. These miners give the best performance that I’ve found. However, you’ll need to compile them yourself in order to use them, which isn’t a simple feat. There’s also some manual patching of C code required if you are running multiple graphics cards on OS X. Stay tuned!

Bitcoin Mining on Mac OS X – BitMinter

Bitcoin

The media is buzzing these days with stories about bitcoin, the most popular of available crypto currencies. First proposed in 2008 and implemented in 2009, recent bubbles and crashes in the exchange-rate for the bitcoin have everyone talking about it. And while the volatility and investment possibilities of bitcoin are intriguing, to me the truly interesting aspect is the role of the bitcoin miner.

As the name implies, bitcoin miners – which are generally either computers or specialized hardware – are responsible for mining new bitcoins. However, that is not their primary function. Those individuals running bitcoin mining software are, in effect, running the bitcoin transaction processing network in a peer-to-peer fashion. You can think of this as another distributed computing system like SETI@home and Folding@home. By using your computer hardware’s spare cycles you can contribute to a growing, global, distributed crypto currency. If that’s your thing.

And you can actually come out ahead financially. Now, arguably, this won’t last much longer. There is specialized hardware on the horizon that may make it much less profitable to mine bitcoins. But, for the time being, if you already have a Radeon 5x series or higher GPU then there’s a decent chance you could do this and make a couple of dollars a day (US, not bitcoin). Check out this hardware chart and this calculator for more information.

As it happens the most recent Mac Pros ship with Radeon 5x series GPU’s and can use 6x series Radeons with OS X Lion. However, most of the bitcoin mining software is aimed at Windows and Linux. There really aren’t a lot of options available for mining bitcoins on OS X without a little extra effort.

In this series of articles I’ll talk about three options for bitcoin mining on OS X:

  1. BitMinter – a Java app that uses OpenCL for mining
  2. GUIMiner – a GUI wrapper for a Python OpenCL miner
  3. cgminer & bfgminer – native command-line utilities that use OpenCL to mine

BitMinter

BitMinter is a great service for trying out bitcoin mining with minimal effort. BitMinter functions as a bitcoin pool and as mining software. Their mining software is a Java app. While Java can be a good choice for providing a single app for multiple platforms, recent changes in the Java runtime environment on OS X mean that the BitMinter app may not run without some work.

If you are running the latest version of Mac OS X and attempt to launch the BitMinter Java app, the odds are you’ll be faced with this dialog:

No Runtime Environment

If that is the case, simply click on this knowledgebase link from Apple and follow the instructions. Afterward you should be able to launch the .jnlp files by double-clicking them. If you are still having trouble, launch them from the command line with the javaws utility:

javaws beta.jnlp

Once the BitMinter app fires up, you’ll see collapsable panes for each CPU and GPU. It is absolutely not worth mining bitcoins on your CPU at this point (though you could look into Litecoins to put your CPU to work). To start mining, click the Engine Start button for each of your GPU’s.

BitMinter

And you are now off and mining. You should see a Mh/s readout in the status bar. This is the number of hashes per second your hardware is performing. And, while the BitMinter miner is one of the easiest to try on OS X, it is worth noting a few downsides:

  • Your performance will be much better with native command-line miners such as cgminer or bfgminer
  • You are forced to use BitMinter as your mining pool when using the BitMinter miner

So far I’ve glossed over the idea of mining “pools”. While this is outside the scope of this article, know that you will need to pick a pool to participate in. Mining pools are collections of individuals mining common blocks of bitcoin transactions. This means you get paid small fractions every couple of hours instead of waiting months or even years for larger, rounder payouts. They have different payout methods and percentages, but BitMinter is a very good one with low fees (1% currently). You can read more about the available bitcoin pools here.

If you’ve tried out mining with BitMinter and it seems interesting to you, watch for future articles on using GUIMiner, cgminer and bfgminer on OS X. These utilities remove the Java requirement and offer performance improvements while also letting you participate in the pool of your choice.