serverspec: RSpec tests for servers configured by Puppet, Chef, Ansible or hand

Why assert server state after Puppet, Chef or Ansible has run

Configuration management tools describe intended state. They do not prove that the machine ended up in it. A Puppet run can report success while a package is held back, a service failed to start, or a template landed with different permissions than the manifest specified. serverspec exists to close that gap: it is a Ruby gem that lets you write RSpec examples about a running server and execute them against that server, so the assertion is about observed state rather than declared state.

The audience is specific. You are already using CFEngine, Puppet, Chef, Ansible, Itamae, or you configure machines by hand, and you are comfortable writing Ruby. The README states the scope plainly: "RSpec tests for your servers configured by Puppet, Chef or anything else." The value is not in a new configuration language. It is in reusing RSpec, its matchers, its formatters and its exit codes, for infrastructure checks.

That choice has consequences. Because the checks are ordinary RSpec examples, they run in your existing Ruby toolchain and can share CI plumbing with application tests. Because they are ordinary RSpec examples, they also inherit RSpec's failure modes: a slow spec is a slow test, and a poorly written expectation is a test that passes for the wrong reason.

How serverspec and specinfra split the work

The repository lists a .gitmodules entry alongside lib/, spec/ and integration-test, and the related search terms include Specinfra. That reflects the architecture: serverspec is the RSpec-facing layer, and specinfra is the backend that actually executes commands on the target. You write a resource-style example; serverspec translates it into a check; specinfra runs that check over the transport you configured, which is why the same spec can target a local machine or a remote host.

The practical effect is that the spec file is portable across backends while the execution details are not. The README does not document the backend configuration in the text available here; it points to serverspec.org for details. Treat the site as the reference for backend selection, and treat the gem as the API surface you write against.

The data flow is one-directional and read-mostly. A spec describes a resource and an expected attribute. The backend inspects the target and returns a value. RSpec compares the two and reports pass or fail. Nothing is remediated. If you want the machine fixed, that is the provisioning tool's job, not serverspec's, and mixing the two responsibilities in one file is a design mistake.

Installing the serverspec gem and running a first check

serverspec is distributed as a Ruby gem, so the installation path is the standard one. The README does not give end-user install steps; the only command it gives is the one for the repository's own test suite, bundle exec rake, with the warning that using rspec alone will not work. For your own project, the documented route is to get the gem from rubygems.org, where the badge in the README points, and then follow serverspec.org for the initialisation procedure, which the README does not reproduce.

The one command the README does state verbatim is the gem's own test invocation.

bundle exec rake

That command runs the serverspec test suite inside the repository itself, not your server specs. What you should see is the Rake task driving the suite to completion; the README notes that invoking rspec directly does not work, so do not substitute it.

The repository also ships WINDOWS_SUPPORT.md and appveyor.yml, which indicates Windows targets are handled as a separate concern from the main path. Read that file before assuming a Windows check behaves like its Linux equivalent. Because the README shows no further command, flag, port or environment variable for the gem, anything beyond bundle exec rake has to come from serverspec.org rather than from the repository text.

Where serverspec is the wrong tool

The maintenance policy in the README is the first limitation, and it is unusual enough to quote: "The person who found a bug should fix the bug by themself." The project accepts pull requests only and has issues disabled. If you find a bug and cannot fix it, the documented path is to send a pull request with test code that reproduces it. For a team without Ruby capacity, that is a real cost, not a formality.

The second limitation is scope. serverspec checks a machine you point it at. It does not inventory your fleet, does not aggregate results across hosts by itself, and does not ship a compliance rule library you can switch on. If your requirement is "tell me which of four hundred hosts violate a baseline," serverspec is a component in that pipeline, not the pipeline.

The third is the boundary with the provisioning tool. serverspec is a verifier, not a fixer. A failing spec after a Chef run means you investigate the cookbook, not the spec. Teams that expect the test suite to converge the machine will be disappointed, and teams that let specs drift out of sync with manifests end up maintaining two descriptions of the same server that disagree.

Finally, the README's own test command is a reminder that this is a Ruby project with a Ruby project's setup friction. bundle exec rake is required for the gem's tests; rspec alone will not work.

serverspec vs inspec and the alternatives question

The most common comparison is serverspec against inspec, and the difference is architectural rather than cosmetic. serverspec is an RSpec extension: your specs are Ruby files, your assertions are RSpec matchers, and your extensions are Ruby code. inspec defines its own DSL and its own resource set, and it is designed to run as a standalone compliance tool with profiles that can be distributed and executed without a Ruby project around them.

That difference decides the choice. If your team already lives in Ruby and wants server checks in the same CI job as application specs, serverspec fits without a second toolchain. If you want a self-contained profile that a non-Ruby operator can run, or you want a rule library to adopt rather than write, serverspec is the wrong shape and you will spend your time rebuilding what a profile-based tool gives you.

The related searches also include serverspec python, which reflects a real constraint: serverspec is Ruby, and there is no Python port of the gem described here. A Python team can still shell out to RSpec, but at that point the ergonomic argument for serverspec is gone. The honest answer for a Python shop is to use a tool native to that ecosystem.

Against plain shell scripts, the trade is different again. A shell script is faster to write and has no gem dependency; serverspec gives you structured output, per-example reporting and reusable resource matchers. If your checks are five lines long and run once, the shell script wins. If they are fifty and run on every deploy, the structure pays for itself.

Maintenance, licensing and what the repository tells you about cost

The last push to the default branch was on 2026-08-30, and the most recent release listed is v2.43.0 from 2025-04-24. The gap before that is visible in the release list: v2.42.3 in 2023 and v2.42.2 in 2023. That pattern says releases are infrequent and driven by accumulated changes rather than a schedule. Plan for pinning a version and reading the changelog before upgrading, rather than assuming a steady stream of small updates.

The licence is MIT, stated in the repository metadata and in LICENSE.txt at the top level. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. This is not legal advice, and if you redistribute serverspec inside a product you should have your own counsel read the terms rather than relying on a summary.

The upgrade surface is the gem plus its specinfra backend. Because the backend is where target-specific behaviour lives, an upgrade can change how a check executes on a given platform even when your spec files are untouched. That is the argument for running your serverspec suite in CI on every dependency bump, and for keeping the suite small enough that a failure is diagnosable.

Development cost is the other line item. The README's contributing section is a standard fork, branch, commit, push, pull request flow, and the repository carries a Gemfile, Guardfile and Rakefile, so contributing is a normal Ruby workflow. Budget for it, because the maintenance policy makes self-fixing the expected path when something breaks.

Editorial conclusion

Adopt serverspec when your provisioning is already declarative and you want the post-convergence state asserted in Ruby, with no agent on the target. Do not adopt it if you need an inventory-wide compliance scanner with its own DSL, or if you cannot commit to writing the specs yourself, because the maintenance policy puts bug fixes and features on the reporter. Before committing, verify that your target operating system is covered by the specinfra backend, and confirm which Ruby versions your CI runs, since the repository ships a Gemfile, a Guardfile and a Rakefile that define the development environment.

Frequently asked questions

Official sources

1. License: MIT
2. mizzy/serverspec on GitHub
3. Project website
4. README
5. Releases