Debian Codegraph @

ansible_collections/netapp/ontap/tests/unit/framework/zapi_factory.py

raw
1 # (c) 2022, NetApp, Inc
2 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
3 # Author: Laurent Nicolas, [email protected]
4
5 """ unit tests for Ansible modules for ONTAP:
6 utility to build REST responses and errors, and register them to use them in testcases.
7
8 1) at the module level, define the ZAPI responses:
9 ZRR = zapi_responses() if you're only interested in the default ones: 'empty', 'error', ...
10 or
11 ZRR = zapi_responses(dict) to use the default ones and augment them:
12 a key identifies a response name, and the value is an XML structure.
13
14 2) create a ZAPI XML response or error using
15 build_zapi_response(contents, num_records=None)
16 build_zapi_error(errno, reason)
17
18 Typically, these will be used with zapi_responses as
19
20 ZRR = zapi_responses({
21 'aggr_info': build_zapi_response(aggr_info),
22 'object_store_info': build_zapi_response(object_store_info),
23 'disk_info': build_zapi_response(disk_info),
24 })
25
26 3) in each test function, create a list of (event, response) using zapi_responses (and rest_responses)
27 def test_create(self):
28 register_responses([
29 ('aggr-get-iter', ZRR['empty']),
30 ('aggr-create', ZRR['empty']),
31 ('aggr-get-iter', ZRR['empty']),
32 ])
33
34 See ansible_collections/netapp/ontap/tests/unit/plugins/modules/test_na_ontap_aggregate.py
35 for an example.
36 """
37
38 from __future__ import (absolute_import, division, print_function)
39 __metaclass__ = type
40
41 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
42
43 # name: (dict, num_records)
44 # dict is translated into an xml structure, num_records is None or an integer >= 0
45 _DEFAULT_RESPONSES = {
46 'empty': ({}, None),
47 'success': ({}, None),
48 'no_records': ({'num-records': '0'}, None),
49 'one_record_no_data': ({'num-records': '1'}, None),
50 'version': ({'version': 'zapi_version'}, None),
51 'cserver': ({
52 'attributes-list': {
53 'vserver-info': {
54 'vserver-name': 'cserver'
55 }
56 }}, 1),
57 }
58 # name: (errno, reason)
59 # errno as int, reason as str
60 _DEFAULT_ERRORS = {
61 'error': (12345, 'synthetic error for UT purpose'),
62 'error_missing_api': (13005, 'Unable to find API: xxxx on data vserver')
63 }
64
65
66 def get_error_desc(error_code):
67 return next((err_desc for err_num, err_desc in _DEFAULT_ERRORS.values() if err_num == error_code),
68 'no registered error for %d' % error_code)
69
70
71 def zapi_error_message(error, error_code=12345, reason=None, addal=None):
72 if reason is None:
73 reason = get_error_desc(error_code)
74 msg = "%s: NetApp API failed. Reason - %s:%s" % (error, error_code, reason)
75 if addal:
76 msg += addal
77 return msg
78
79
80 def build_raw_xml_response(contents, num_records=None, force_dummy=False):
81 top_contents = {'results': contents}
82 xml, valid = build_zapi_response(top_contents)
83 if valid == 'valid' and not force_dummy:
84 return xml.to_string()
85 return b'<xml><results status="netapp-lib is missing"/></xml>'
86
87
88 def build_zapi_response(contents, num_records=None):
89 ''' build an XML response
90 contents is translated into an xml structure
91 num_records is None or an integer >= 0
92 '''
93 if not netapp_utils.has_netapp_lib():
94 # do not report an error at init, as it breaks ansible-test checks
95 return 'build_zapi_response: netapp-lib is missing', 'invalid'
96 if num_records is not None:
97 contents['num-records'] = str(num_records)
98 response = netapp_utils.zapi.NaElement('results')
99 response.translate_struct(contents)
100 response.add_attr('status', 'passed')
101 return (response, 'valid')
102
103
104 def build_zapi_error(errno, reason):
105 ''' build an XML response
106 errno as int
107 reason as str
108 '''
109 if not netapp_utils.has_netapp_lib():
110 return 'build_zapi_error: netapp-lib is missing', 'invalid'
111 response = netapp_utils.zapi.NaElement('results')
112 response.add_attr('errno', str(errno))
113 response.add_attr('reason', reason)
114 return (response, 'valid')
115
116
117 class zapi_responses:
118
119 def __init__(self, adict=None, allow_override=True):
120 self.responses = {}
121 for key, value in _DEFAULT_RESPONSES.items():
122 self.responses[key] = build_zapi_response(*value)
123 for key, value in _DEFAULT_ERRORS.items():
124 if key in self.responses:
125 raise KeyError('duplicated key: %s' % key)
126 self.responses[key] = build_zapi_error(*value)
127 if adict:
128 for key, value in adict.items():
129 if not allow_override and key in self.responses:
130 raise KeyError('duplicated key: %s' % key)
131 self.responses[key] = value
132
133 def _get_response(self, name):
134 try:
135 value, valid = self.responses[name]
136 # sanity checks for netapp-lib are deferred until the test is actually run
137 if valid != 'valid':
138 print("Error: Defer any runtime dereference, eg ZRR['key'], until runtime or protect dereference under has_netapp_lib().")
139 raise ImportError(value)
140 return value, valid
141 except KeyError:
142 raise KeyError('%s not registered, list of valid keys: %s' % (name, self.responses.keys()))
143
144 def __getitem__(self, name):
145 return self._get_response(name)
146
147 def __contains__(self, name):
148 return name in self.responses