CemWinSpec

cem_win_spec is a gem that provides CLI for running CEM RSpec test on a remote Windows machine.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add cem_win_spec

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install cem_win_spec

Usage

CemWinSpec requires that you have gcloud installed and configured to connect to the GCP instance that you want to run the tests on.

The gem provides a CLI that can be used to run CEM RSpec tests on a remote Windows machine. The CLI help menu can be viewed by running:

$ cem-win-spec --help
Usage: cem-win-spec [options]
    -v, --version                    Print version and exit
    -o, --operation [OPERATION]      Operation to perform (spec, clean_fixture_cache)
    -q, --quiet                      Suppress output
    -d, --debug                      Enable debug output on the console
    -l, --log-level [LEVEL]          Set log level (debug, info, warn, error, fatal)
    -L, --log-file [FILE]            Log output to file
    -f, --log-format [FORMAT]        Set log format(file, text, json, github_action
    -h, --help                       Print this help

The operation option can be used to specify the operation to perform. The CLI supports the following operations:

spec - Run the RSpec tests on the remote Windows machine (default)
clean_fixture_cache - Clean the RSpec fixture cache on the remote Windows machine

The quiet option can be used to suppress all console output. This option can be used in conjunction with the log-file option to suppress console output and only log to a file.

The debug option only affects the console output and does not affect the log file output.

The log-level option can be used to set the log level for the log file output. The default log level is debug.

The log-file option can be used to set the log file path. If this is not set, no log file will be created.

The log-format option can be used to set the log format. The default log format is text for the console and file for the log file. The github_action format is designed to be used with GitHub Actions. Setting this affects both the console and log file output.

Configuration

CemWinSpec takes it's configuration from environment variables. The following environment variables are required:

  • GCP_INSTANCE_NAME - The name of the GCP Windows instance to run the tests on
  • WINRM_USERNAME - The username to use when connecting to the GCP instance
  • WINRM_PASSWORD - The password to use when connecting to the GCP instance

The following environment variables may be required if they cannot be determined from gcloud:

  • GCP_PROJECT_ID - The GCP project ID that the instance is in
  • GCP_ZONE - The GCP zone that the instance is in

The following environment variables are optional:

  • CEM_WIN_SPEC_PATTERN - The pattern to use when running the tests. Defaults to spec/{classes,defines,functions,unit}/**/*_spec.rb
  • CEM_WIN_SPEC_FAIL_FAST - If set to true, the tests will stop running after the first failure. Defaults to false
  • CEM_WIN_SPEC_TRACE - If set to true, Rake will output a full backtrace for any halting errors. Defaults to false
  • CEM_WIN_SPEC_FORMAT - The RSpec output format to use when running the tests. Defaults to progress

The following environment variables have an effect, but should not be set manually:

  • CI - If set, the tests will run in CI mode which changes the logging output to be more suitable for GitHub Actions
  • GITHUB_ACTIONS - If set, the tests will run in CI mode which changes the logging output to be more suitable for GitHub Actions

Adding to module Rakefile

The following line must be added to the Rakefile in the CEM Windows repository:

require 'cem_win_spec/rake_tasks' if Bundler.rubygems.find_name('cem_win_spec').any?

This will add the cem_win_spec task namespace to the Rakefile, along with the tasks run, prep, and parallel_spec. The tasks are used by cem_win_spec to run the tests on the remote Windows machine and should not be used directly.