Serverspec Documentation

For Windows testing using the winrm backend, the generated spec_helper.rb requires specific credentials and endpoint configuration.

Note that the setup template uses placeholders for <username> and <password> which must be updated in the resulting spec/spec_helper.rb. The endpoint is typically constructed as http://<TARGET_HOST>:5985/wsman.

# Example of the WinRM configuration logic generated in spec_helper.rb
user = <username>
pass = <password>
endpoint = "http://#{ENV['TARGET_HOST']}:5985/wsman"

opts = {
  user: user,
  password: pass,
  endpoint: endpoint,
  operation_timeout: 300,
  no_ssl_peer_verification: false,
}

winrm = ::WinRM::Connection.new(opts)
Specinfra.configuration.winrm = winrm

When setting up a UN*X environment with an ssh backend, Serverspec::Setup can integrate with Vagrant. If you choose to use a Vagrant instance, the generated spec_helper.rb will:

1. Run vagrant up <host> to ensure the machine is running.
2. Use vagrant ssh-config <host> to extract connection details.
3. Automatically configure Net::SSH options using the extracted configuration.

This allows you to run tests against virtual machines managed by Vagrant without manually managing SSH keys or hostnames.

# Example of how the generated spec_helper.rb handles Vagrant
`vagrant up #{host}`

config = Tempfile.new('', Dir.tmpdir)
config.write(`vagrant ssh-config #{host}`)
config.close

options = Net::SSH::Config.for(host, [config.path])
set :host,        options[:host_name] || host
set :ssh_options, options

The Serverspec::Setup utility generates a Rakefile that allows you to run tests for specific target hosts. The Rakefile defines a spec namespace with tasks for each directory found in spec/*.

To run all tests, use:

rake spec:all

To run tests for a specific host (e.g., a host named my-server), use:

rake spec:my-server

Each task sets the ENV['TARGET_HOST'] environment variable, which the spec_helper.rb uses to determine the connection target.

The Serverspec::Type::Command class provides methods to inspect the results of a command execution, including its standard output, standard error, and exit status. This is useful for verifying that a command ran successfully and produced the expected output.

Key methods available:

• stdout: Returns the standard output of the command as a string.
• stdout_as_json: Parses the standard output as JSON and returns the resulting object. This requires the multi_json gem to be available.
• stderr: Returns the standard error of the command as a string.
• exit_status: Returns the exit status of the command as an integer.

The File resource allows you to inspect the content of a file and parse it directly into structured data formats.

• content: Returns the raw string content of the file.
• content_as_json: Parses the file content as JSON using MultiJson.
• content_as_yaml: Parses the file content as YAML.

This is useful for testing configuration files where you need to verify specific keys or values within a structured format.

Use these methods to perform assertions on the temporal validity and intended use of a certificate:

• certificate?: Returns true if the file is a valid X.509 certificate.
• valid?: Returns true if the current time is between the certificate's notBefore and notAfter dates.
• validity_in_days: Returns the number of days remaining until the certificate expires. Returns 0 if the command fails.
• has_purpose?(p): Returns true if the certificate is valid for the specified purpose p (e.g., sslclient, sslserver).

The process resource type allows you to verify the state, ownership, and count of running processes on a system. You can check if a process is running, identify its owner (user/group), and verify the number of instances currently active.

Available methods include:

• running?: Returns true if the process is currently running, false otherwise.
• user: Returns the username of the process owner.
• group: Returns the group name of the process owner.
• count: Returns the integer number of running instances of the process.
• Dynamic attributes: You can call get_column(keyword) via method_missing to retrieve other process attributes (e.g., cmdline, etime) if the underlying runner supports them.

The be_listening matcher (implemented via the Serverspec::Type::Port class) allows you to verify if a specific network port is listening on a given protocol and local address.

Supported protocols include:

• udp
• tcp
• tcp6
• udp6

When using the matcher, you can optionally specify the protocol and the local IP address (IPv4 or IPv6). If an invalid protocol is provided, an ArgumentError is raised. If an invalid IP address is provided, an ArgumentError is raised stating that the matcher requires a valid IPv4 or IPv6 address.

The readable?, writable?, and executable? methods can be used to check if a specific user has access to a file, rather than just checking the general permission bits.

To check access for a specific user, pass the username as the by_user argument. If by_user is provided, the method checks if that specific user can perform the action (read, write, or execute).