cisco_node_utils_mgx 2.1.0.1

data/spec/environment_spec.rb

@@ -0,0 +1,384 @@
+require_relative 'spec_helper.rb'
+require 'cisco_node_utils/environment'
+require 'cisco_node_utils/client'
+
+class << Cisco::Environment
+  attr_writer :environments
+end
+
+describe Cisco::Environment do
+  after(:each) do
+    # Revert to default environment data
+    Cisco::Environment.environments = {}
+  end
+
+  describe '.data_from_file' do
+    it 'handles File.expand_path errors' do
+      expect(File).to receive(:expand_path).and_raise(ArgumentError)
+      expect(Cisco::Environment.data_from_file('~/foo/bar.yaml')).to be_empty
+    end
+
+    it 'handles nonexistent files' do
+      expect(File).to receive(:file?).and_return(false)
+      expect(Cisco::Environment.data_from_file('/foo/bar.yaml')).to be_empty
+    end
+
+    it 'handles unreadable files' do
+      expect(File).to receive(:file?).and_return(true)
+      expect(File).to receive(:readable?).and_return(false)
+      expect(Cisco::Environment.data_from_file('/foo/bar.yaml')).to be_empty
+    end
+
+    it 'handles YAML errors' do
+      expect(File).to receive(:file?).and_return(true)
+      expect(File).to receive(:readable?).and_return(true)
+      error = Psych::SyntaxError.new('/foo/bar.yaml', 1, 1, 0, 'foo', 'bar')
+      expect(YAML).to receive(:load_file).and_raise(error)
+      # Catch the error log message Environment will generate:
+      expect(Cisco::Logger).to receive(:error).once
+      expect(Cisco::Environment.data_from_file('/foo/bar.yaml')).to eq({})
+    end
+  end
+
+  describe '.merge_config' do
+    it 'merges valid content' do
+      base = { 'hello' => {
+        host:     '2.2.2.2',
+        port:     57_799,
+        username: nil,
+        password: nil,
+        cookie:   nil,
+      } }
+      expect(Cisco::Environment).to receive(:data_from_file).and_return(
+        'hello' => { host: '1.1.1.1' }, 'goodbye' => { password: 'foo' })
+      expect(Cisco::Environment.merge_config('/foo/bar.yaml', base)).to eq(
+        'hello'   => {
+          host:     '1.1.1.1',
+          port:     57_799,
+          username: nil,
+          password: nil,
+          cookie:   nil,
+        },
+        'goodbye' => {
+          host:     nil,
+          port:     nil,
+          username: nil,
+          password: 'foo',
+          cookie:   nil,
+        },
+      )
+    end
+  end
+
+  describe '.add_env' do
+    it 'rejects empty environment name' do
+      expect { described_class.add_env('', {}) }.to \
+        raise_error(ArgumentError, 'empty environment name')
+    end
+
+    it 'rejects incorrectly typed environment hash' do
+      expect { described_class.add_env('default', 'hash') }.to \
+        raise_error(TypeError, 'invalid environment hash')
+    end
+
+    context 'environment can be loaded by funcion' do
+      expected = {
+        host:     '192.168.1.1',
+        port:     nil,
+        username: 'admin',
+        password: 'admin',
+        cookie:   nil,
+      }
+      it 'can be loaded explicitly by name' do
+        described_class.add_env('test', expected)
+        expect(Cisco::Environment.environment('test')).to eq(expected)
+      end
+
+      it 'can be default' do
+        described_class.add_env('default', expected)
+        expect(Cisco::Environment.environment).to eq(expected)
+      end
+    end
+  end
+
+  describe '.environments' do
+    before(:each) do
+      allow(Cisco::Environment).to receive(:data_from_file).and_return({})
+    end
+
+    it 'is empty by default' do
+      expect(Cisco::Environment.environments).to be_empty
+    end
+
+    global_config = {
+      'default' => {
+        host:   '127.0.0.1',
+        port:   57_400,
+        cookie: nil,
+      },
+      'global'  => {
+        username: 'global',
+        password: 'global',
+        cookie:   nil,
+      },
+    }
+
+    user_config = {
+      'default' => {
+        port:     57_799,
+        username: 'user',
+        cookie:   nil,
+      },
+      'user'    => {
+        username: 'user',
+        password: 'user',
+        cookie:   nil,
+      },
+    }
+
+    it 'loads data from global config if present' do
+      expect(Cisco::Environment).to receive(:data_from_file).with(
+        '/etc/cisco_node_utils.yaml').and_return(global_config)
+      env = Cisco::Environment.environments
+      env.each do |key, hash|
+        # The env hash should be fully populated with keys
+        # Any keys unspecified in the data should be nil
+        %I(host port username password).each do |hash_key|
+          expect(hash.fetch(hash_key)).to \
+            eq(global_config[key].fetch(hash_key, nil))
+        end
+      end
+    end
+
+    it 'loads data from user config if present' do
+      expect(Cisco::Environment).to receive(:data_from_file).with(
+        '~/cisco_node_utils.yaml').and_return(user_config)
+      env = Cisco::Environment.environments
+      env.each do |key, hash|
+        # The env hash should be fully populated with keys
+        # Any keys unspecified in the data should be nil
+        %I(host port username password).each do |hash_key|
+          expect(hash.fetch(hash_key)).to \
+            eq(user_config[key].fetch(hash_key, nil))
+        end
+      end
+    end
+
+    it 'uses both files if present but user data takes precedence' do
+      expect(Cisco::Environment).to receive(:data_from_file).with(
+        '/etc/cisco_node_utils.yaml').and_return(global_config)
+      expect(Cisco::Environment).to receive(:data_from_file).with(
+        '~/cisco_node_utils.yaml').and_return(user_config)
+      expect(Cisco::Environment.environments).to eq(
+        'default' => {
+          host:     '127.0.0.1', # global config
+          port:     57_799, # user overrides global
+          username: 'user', # user config
+          password: nil, # auto-populated with nil
+          cookie:   nil,
+        },
+        'global'  => { # global config
+          host:     nil,
+          port:     nil,
+          username: 'global',
+          password: 'global',
+          cookie:   nil,
+        },
+        'user'    => { # user config
+          host:     nil,
+          port:     nil,
+          username: 'user',
+          password: 'user',
+          cookie:   nil,
+        },
+      )
+    end
+
+    it 'loaded file can be overridden by add_env' do
+      expect(Cisco::Environment).to receive(:data_from_file).with(
+        '/etc/cisco_node_utils.yaml').and_return(global_config)
+      expect(Cisco::Environment).to receive(:data_from_file).with(
+        '~/cisco_node_utils.yaml').and_return(user_config)
+      expect(Cisco::Environment.environments).to eq(
+        'default' => {
+          host:     '127.0.0.1', # global config
+          port:     57_799, # user overrides global
+          username: 'user', # user config
+          password: nil, # auto-populated with nil
+          cookie:   nil,
+        },
+        'global'  => { # global config
+          host:     nil,
+          port:     nil,
+          username: 'global',
+          password: 'global',
+          cookie:   nil,
+        },
+        'user'    => { # user config
+          host:     nil,
+          port:     nil,
+          username: 'user',
+          password: 'user',
+          cookie:   nil,
+        },
+      )
+      added_env = {
+        host:     '192.168.1.1',
+        port:     nil,
+        username: 'admin',
+        password: 'admin',
+        cookie:   nil,
+      }
+      overide_defult = {
+        host:     '192.168.2.2',
+        port:     nil,
+        username: 'overridden',
+        password: 'overridden',
+        cookie:   nil,
+      }
+      described_class.add_env('added', added_env)
+      described_class.add_env('default', overide_defult)
+      expect(Cisco::Environment.environments).to eq(
+        'added'   => { # added by method
+          host:     '192.168.1.1',
+          port:     nil,
+          username: 'admin',
+          password: 'admin',
+          cookie:   nil,
+        },
+        'default' => {
+          host:     '192.168.2.2', # method overrides files
+          port:     nil, # method overrides files
+          username: 'overridden', # method overrides files
+          password: 'overridden', # method overrides files
+          cookie:   nil, # auto-popuplated with nil
+        },
+        'global'  => { # global config
+          host:     nil,
+          port:     nil,
+          username: 'global',
+          password: 'global',
+          cookie:   nil,
+        },
+        'user'    => { # user config
+          host:     nil,
+          port:     nil,
+          username: 'user',
+          password: 'user',
+          cookie:   nil,
+        },
+      )
+    end
+  end
+
+  context '.environment' do
+    context 'with no config files available' do
+      before(:each) do
+        allow(Cisco::Environment).to receive(:data_from_file).and_return({})
+      end
+
+      it 'returns DEFAULT_ENVIRONMENT when called with no args' do
+        expect(Cisco::Environment.environment).to \
+          eq(Cisco::Environment::DEFAULT_ENVIRONMENT)
+      end
+      it 'returns DEFAULT_ENVIRONMENT when requested by name as "default"' do
+        expect(Cisco::Environment.environment('default')).to \
+          eq(Cisco::Environment::DEFAULT_ENVIRONMENT)
+      end
+    end
+
+    context 'with examples in docs/cisco_node_utils.yaml.example' do
+      before(:each) do
+        allow(File).to receive(:file?).and_return(true)
+        allow(File).to receive(:readable?).and_return(true)
+        allow(YAML).to receive(:load_file).and_wrap_original do |orig|
+          orig.call(File.expand_path('docs/cisco_node_utils.yaml.example'))
+        end
+      end
+
+      context 'the "nxapi_local" example' do
+        expected = {
+          host:     nil,
+          port:     nil,
+          username: nil,
+          password: nil,
+          cookie:   nil,
+        }
+        it 'can be loaded explicitly by name' do
+          expect(Cisco::Environment.environment('nxapi_local')).to eq(expected)
+        end
+        it 'can be specified as the default then loaded implicitly' do
+          Cisco::Environment.default_environment_name = 'nxapi_local'
+          expect(Cisco::Environment.environment).to eq(expected)
+        end
+        it 'is valid configuration for the NXAPI client' do
+          hash = Cisco::Environment.environment('nxapi_local')
+          Cisco::Client::NXAPI.validate_args(hash)
+        end
+      end
+
+      context 'the "nxapi_remote" example' do
+        expected = {
+          host:     '192.168.1.100',
+          port:     nil,
+          username: 'devops',
+          password: 'devops',
+          cookie:   nil,
+        }
+        it 'can be loaded explicitly by name' do
+          expect(Cisco::Environment.environment('nxapi_remote')).to eq(expected)
+        end
+        it 'can be specified as the default then loaded implicitly' do
+          Cisco::Environment.default_environment_name = 'nxapi_remote'
+          expect(Cisco::Environment.environment).to eq(expected)
+        end
+        it 'is valid configuration for the NXAPI client' do
+          hash = Cisco::Environment.environment('nxapi_remote')
+          Cisco::Client::NXAPI.validate_args(hash)
+        end
+      end
+
+      context 'the "grpc_local" example' do
+        expected = {
+          host:     nil,
+          port:     57_999,
+          username: 'admin',
+          password: 'admin',
+          cookie:   nil,
+        }
+        it 'can be loaded explicitly by name' do
+          expect(Cisco::Environment.environment('grpc_local')).to eq(expected)
+        end
+        it 'can be specified as default then loaded implicitly' do
+          Cisco::Environment.default_environment_name = 'grpc_local'
+          expect(Cisco::Environment.environment).to eq(expected)
+        end
+        it 'is valid configuration for the gRPC client' do
+          hash = Cisco::Environment.environment('grpc_local')
+          Cisco::Client::GRPC.validate_args(hash)
+        end
+      end
+
+      context 'the "grpc_remote" example' do
+        expected = {
+          host:     '192.168.1.100',
+          port:     nil,
+          username: 'admin',
+          password: 'admin',
+          cookie:   nil,
+        }
+        it 'can be loaded explicitly by name' do
+          expect(Cisco::Environment.environment('grpc_remote')).to eq(expected)
+        end
+        it 'can be specified as default then loaded implicitly' do
+          Cisco::Environment.default_environment_name = 'grpc_remote'
+          expect(Cisco::Environment.environment).to eq(expected)
+        end
+        it 'is valid configuration for the gRPC client' do
+          hash = Cisco::Environment.environment('grpc_remote')
+          Cisco::Client::GRPC.validate_args(hash)
+        end
+      end
+    end
+  end
+end

data/spec/grpc_client_spec.rb

@@ -0,0 +1,23 @@
+require_relative 'spec_helper.rb'
+require 'shared_examples_for_clients'
+require 'cisco_node_utils/client/grpc'
+
+describe Cisco::Client::GRPC do
+  it_behaves_like 'all clients'
+
+  describe '.validate_args' do
+    it 'rejects nil username' do
+      kwargs = { host: '1.1.1.1', username: nil, password: 'bye' }
+      expect { described_class.validate_args(**kwargs) }.to \
+        raise_error(TypeError,
+                    'gRPC client creation failure: username must be specified')
+    end
+
+    it 'rejects nil password' do
+      kwargs = { host: '1.1.1.1', username: 'hi', password: nil }
+      expect { described_class.validate_args(**kwargs) }.to \
+        raise_error(TypeError,
+                    'gRPC client creation failure: password must be specified')
+    end
+  end
+end

data/spec/isolate/all_clients_spec.rb

@@ -0,0 +1,9 @@
+require_relative '../spec_helper.rb'
+
+context 'when both clients are installed' do
+  it 'should have both clients' do
+    require 'cisco_node_utils'
+    expect(Cisco::Client.clients).to eql [Cisco::Client::NXAPI,
+                                          Cisco::Client::GRPC]
+  end
+end

data/spec/isolate/grpc_only_spec.rb

@@ -0,0 +1,16 @@
+require_relative '../spec_helper.rb'
+
+context 'when only gRPC client is installed' do
+  let(:main_self) { TOPLEVEL_BINDING.eval('self') }
+  before(:example) do
+    allow(main_self).to receive(:require).and_wrap_original do |orig, pkg|
+      fail LoadError, pkg if pkg['cisco_node_utils/client/nxapi']
+      orig.call(pkg)
+    end
+  end
+
+  it 'should have gRPC client' do
+    require 'cisco_node_utils'
+    expect(Cisco::Client.clients).to eql [Cisco::Client::GRPC]
+  end
+end

data/spec/isolate/no_clients_spec.rb

@@ -0,0 +1,26 @@
+require_relative '../spec_helper.rb'
+require 'rspec/core'
+
+context 'when no client implementations are installed' do
+  let(:main_self) { TOPLEVEL_BINDING.eval('self') }
+
+  before(:example) do
+    allow(main_self).to receive(:require).and_wrap_original do |orig, pkg|
+      fail LoadError, pkg if pkg['client/nxapi']
+      fail LoadError, pkg if pkg['client/grpc']
+      orig.call(pkg)
+    end
+  end
+
+  it 'should not have any clients' do
+    require 'cisco_node_utils'
+    expect(Cisco::Client.clients).to eql []
+  end
+
+  it 'should fail Client.create' do
+    require 'cisco_node_utils'
+    expect { Cisco::Client.create }.to \
+      raise_error(RuntimeError, 'No client implementations available!')
+  end
+  # TODO
+end

data/spec/isolate/nxapi_only_spec.rb

@@ -0,0 +1,16 @@
+require_relative '../spec_helper.rb'
+
+context 'when only NXAPI client is installed' do
+  let(:main_self) { TOPLEVEL_BINDING.eval('self') }
+  before(:example) do
+    allow(main_self).to receive(:require).and_wrap_original do |orig, pkg|
+      fail LoadError, pkg if pkg['cisco_node_utils/client/grpc']
+      orig.call(pkg)
+    end
+  end
+
+  it 'should have NXAPI client' do
+    require 'cisco_node_utils/client'
+    expect(Cisco::Client.clients).to eql [Cisco::Client::NXAPI]
+  end
+end

data/spec/nxapi_client_spec.rb

@@ -0,0 +1,42 @@
+require_relative 'spec_helper.rb'
+require 'shared_examples_for_clients'
+require 'cisco_node_utils/client/nxapi'
+
+describe Cisco::Client::NXAPI do
+  it_behaves_like 'all clients'
+
+  describe '.validate_args' do
+    it 'accepts nil host, username, and password together' do
+      described_class.validate_args
+    end
+
+    it 'rejects the combination of nil host with non-nil username' do
+      kwargs = { host: nil, username: 'hi', password: nil }
+      expect { described_class.validate_args(**kwargs) }.to \
+        raise_error(ArgumentError)
+    end
+
+    it 'rejects the combination of nil host with non-nil password' do
+      kwargs = { host: nil, username: nil, password: 'bye' }
+      expect { described_class.validate_args(**kwargs) }.to \
+        raise_error(ArgumentError)
+    end
+
+    it 'accepts a host with username and password' do
+      kwargs = { host: '1.1.1.1', username: 'hi', password: 'bye' }
+      described_class.validate_args(**kwargs)
+    end
+
+    it 'rejects a host with nil username' do
+      kwargs = { host: '1.1.1.1', username: nil, password: 'bye' }
+      expect { described_class.validate_args(**kwargs) }.to \
+        raise_error(TypeError, 'username is required')
+    end
+
+    it 'rejects a host with nil password' do
+      kwargs = { host: '1.1.1.1', username: 'hi', password: nil }
+      expect { described_class.validate_args(**kwargs) }.to \
+        raise_error(TypeError, 'password is required')
+    end
+  end
+end

data/spec/schema.yaml

@@ -0,0 +1,82 @@
+# Kwalify schema for cmd_ref YAML files
+
+type: map
+mapping:
+  # List of cases to specifically exclude
+  _exclude: &exclude
+    type: seq
+    sequence:
+      - type: str
+        enum: &filters # Things we can filter by
+          # Platform classes
+          - 'ios_xr'
+          - 'nexus'
+          # Product IDs
+          - 'C3048'
+          - 'C3064'
+          - 'C3132'
+          - 'C3172'
+          - 'N35'
+          - 'N3k'
+          - 'N3k-F'
+          - 'N5k'
+          - 'N6k'
+          - 'N7k'
+          - 'N9k'
+          - 'N9k-F'
+
+  =: &base # default rule - apply to all properties
+    type: map
+    mapping:
+      _exclude: *exclude
+      # Platform and product filters
+      ios_xr: *base
+      nexus: *base
+      C3048: *base
+      C3064: *base
+      C3132: *base
+      C3172: *base
+      N3k: *base
+      N3k-F: *base
+      N5k: *base
+      N6k: *base
+      N7k: *base
+      N9k: *base
+      N9k-F: *base
+      # 'else' case if not matching any filter above
+      else: *base
+      # Generally applicable attributes
+      data_format: &data_format
+        type: str
+        enum: [cli, nxapi_structured]
+      context: &context
+        type: seq
+        sequence:
+          - type: str
+      value:
+        type: str
+      default_only:
+        type: any
+      # Getter-specific attributes
+      auto_default:
+        type: bool
+      default_value:
+        type: any
+      get_command:
+        type: str
+      get_data_format: *data_format
+      get_context: *context
+      get_value:
+        type: any
+      kind:
+        type: str
+        enum: [boolean, int, string, symbol]
+      multiple:
+        type: bool
+      os_version:
+        type: str
+      # Setter-specific attributes
+      set_data_format: *data_format
+      set_context: *context
+      set_value:
+        type: str

data/spec/shared_examples_for_clients.rb

@@ -0,0 +1,14 @@
+shared_examples_for 'all clients' do
+  describe '.validate_args' do
+    %i(host username password).each do |sym|
+      it "rejects non-String #{sym}" do
+        expect { described_class.validate_args(sym => 12) }.to \
+          raise_error(TypeError)
+      end
+      it "rejects empty #{sym}" do
+        expect { described_class.validate_args(sym => '') }.to \
+          raise_error(ArgumentError)
+      end
+    end
+  end
+end