Name Date Size #Lines LOC

..15-May-2020-

gold_tests/H30-May-2020-

include/H19-Nov-2019-

tools/H26-Mar-2020-

unit_tests/H26-Jan-2019-

PipfileH A D11-Jan-20201.2 KiB4136

README.mdH A D23-Dec-201915.3 KiB354280

autest.shH A D23-May-20191 KiB288

test-env-check.shH A D18-Apr-20201.4 KiB5225

README.md

1
2# Getting Started
3
4This directory contains different tests for Apache Trafficserver. It is recommended that all tests move to this common area under the correct location based on the type of test being added.
5
6## Layout
7The current layout is:
8
9**gold_tests/** - contains all the tests that run on the Reusable Gold Testing System (AuTest)
10
11**tools/** - contains programs used to help with testing.
12
13**include/** - contains headers used for unit testing.
14
15## Scripts
16
17To help with easy running of the tests, there is autest.sh and bootstrap.py.
18
19### autest.sh
20This file is a simple wrapper that will call the Reusable Gold Testing System (Autest) program in a pipenv. If the pipenv is not setup, the script will prompt user the missing components. That will set up the Autest on most systems in a Python virtual environment. The wrapper adds some basic options to the command to point to the location of the tests. Use --help for more details on options for running Autest.
21
22### test-env-check.sh
23This script will check for the necessary packages needed to create a pipenv that can run Autest. If any package is missing, the script will alert the user. If all packages are available, it install a virtual environment using the provided Pipfile.
24
25### Pipfile
26This file is used to setup a virtual environment using pipenv. It contains information including the packages needed for Autest.
27A set of commands for pipenv:
28 * **pipenv install**: create virtual environment from the Pipfile. ( If you're going to add tests, add `-d` option to install dev packages )
29 * **pipenv shell**: launch a shell with the environment running(type "exit" to leave the shell).
30 * **pipenv run cmd**: run command in the virtual environment without entering a shell, where cmd is the shell command to run.
31 * **pipenv --rm**: remove the environment.
32
33# Basic setup
34
35AuTest can be run using the script file autest.sh listed above. Run the file from the tests/ directory followed by --ats-bin and the bin name. (ie ~/ats/bin) This will run the wrapper for the tests.
36
37To run autest manually, the recommended way is to follow these steps:
381. **pipenv install**: create the virtual environment(only needed once).
392. **pipenv shell**: enter a shell in the virtual environment(type "exit" to leave the shell).
403. **cd gold_tests**: enter the directory containing the test files.
414. **autest --ats-bin user_ats_bin**: run autest where user_ats_bin is the bin directory in the user's ats directory.
42
43# Advanced setup
44
45AuTest and the relevant tools can be install manually instead of using the wrapper script. By doing this, it is often easier to debug issues with the testing system, or the tests. There are two ways this can be done.
461. Run the bootstrap script then source the path with a "source ./env-test/bin/activate" command. At this point autest command should run without the wrapper script
472. Make sure you install python 3.5 or better on your system. From there install these python packages ( ie pip install ):
48  - hyper
49  - git+https://bitbucket.org/autestsuite/reusable-gold-testing-system.git
50  - [traffic-replay](https://bitbucket.org/autestsuite/trafficreplay/src/master/) (This will automatically install [MicroDNS](https://bitbucket.org/autestsuite/microdns/src/master/), [MicroServer](https://bitbucket.org/autestsuite/microserver/src/master/), [TrafficReplayLibrary](https://bitbucket.org/autestsuite/trafficreplaylibrary/src/master/), and dnslib as part of the dependencies.)
51
52# Writing tests for AuTest
53When writing for the AuTest system please refer to the current [Online Documentation](https://autestsuite.bitbucket.io/) for general use of the system. To use CurlHeader tester for testing output of curl, please refer to [CurlHeader README](gold_tests/autest-site/readme.md)
54
55## Documentation of AuTest extension for ATS.
56Autest allows for the creation of extensions to help specialize and simplify test writing for a given application domain. Minus API addition the extension code will check that python 3.5 or better is used. There is also a new command line argumented added specifically for Trafficserver:
57
58--ats-bin < path to bin directory >
59
60This command line argument will point to your build of ATS you want to test. At this time v6.0 or newer of Trafficserver should work.
61
62### MakeATSProcess(name,command=[traffic_server], select_ports=[True], enable_tls=[False])
63 * name - A name for this instance of ATS
64 * command - optional argument defining what process to use. Defaults to traffic_server.
65 * select_ports - have the testing system automatically select a nonSSL port to use for this instance of ATS
66 * enable_tls - have the testing system also auto-select a SSL port to use (NOTE: This does not set up certs and other TLS-related configs.)
67
68This function will define a sandbox for an instance of trafficserver to run under. The function will return a AuTest process object that will have a number of files and variables define for making it easier to define a test. If both *select_ports* and *enable_tls* are toggled to **False**, then the test writer will be responsible for setting up the ports and the ready condition for an instance of ATS.
69
70#### Environment
71The environment of the process will have a number of added environment variables to control trafficserver running the in the sandbox location correctly. This can be used to easily setup other commands that should run under same environment.
72
73##### Example
74
75```python
76# Define default ATS
77ts=Test.MakeATSProcess("ts")
78# Call traffic_ctrl to set new generation
79tr=Test.AddTestRun()
80tr.Processes.Default.Command='traffic_ctl'
81tr.Processes.Default.ReturnCode=0
82# set the environment for traffic_control to run in to be the same as the "ts" ATS instance
83tr.Processes.Default.Env=ts.Env
84```
85
86#### Variables
87These are the current variables that are defined dynamically for Trafficserver
88
89port - the ipv4 port to listen on
90portv6 - the ipv6 port to listen on
91admin_port - the admin port used. This is set even is select_port is False
92
93#### File objects
94A number of file objects are defined to help with adding values to a given configuration value to for a test, or testing a value exists in a log file. File that are defined currently are:
95
96##### log files
97 * squid.log
98 * error.log
99 * diags.log
100
101##### config files
102 * records.config
103 * cache.config
104 * congestion.config
105 * hosting.config
106 * ip_allow.config
107 * logging.yaml
108 * parent.config
109 * plugin.config
110 * remap.config
111 * socks.config
112 * splitdns.config
113 * ssl_multicert.config
114 * storage.config
115 * volume.config
116
117#### Examples
118
119Create a server
120
121```python
122# don't set ports because a config file will set them
123ts1 = Test.MakeATSProcess("ts1",select_ports=False)
124ts1.Setup.ts.CopyConfig('config/records_8090.config','records.config')
125```
126
127Create a server and get the dynamic port value
128
129```python
130# Define default ATS
131ts=Test.MakeATSProcess("ts")
132#first test is a miss for default
133tr=Test.AddTestRun()
134# get port for command from Variables
135tr.Processes.Default.Command='curl "http://127.0.0.1:{0}" --verbose'.format(ts.Variables.port)
136
137```
138
139Add value to a configuration file
140```python
141# setup some config file for this server
142ts.Disk.records_config.update({
143            'proxy.config.body_factory.enable_customizations': 3,  # enable domain specific body factory
144            'proxy.config.http.cache.generation':-1, # Start with cache turned off
145            'proxy.config.config_update_interval_ms':1,
146        })
147ts.Disk.plugin_config.AddLine('xdebug.so')
148ts.Disk.remap_config.AddLines([
149            'map /default/ http://127.0.0.1/ @plugin=generator.so',
150            #line 2
151            'map /generation1/ http://127.0.0.1/' +
152            ' @plugin=conf_remap.so @pparam=proxy.config.http.cache.generation=1' +
153            ' @plugin=generator.so',
154            #line 3
155            'map /generation2/ http://127.0.0.1/' +
156            ' @plugin=conf_remap.so @pparam=proxy.config.http.cache.generation=2' +
157            ' @plugin=generator.so'
158        ])
159```
160
161### CopyConfig(file, targetname=None, process=None)
162* file - name of the file to copy. Relative paths are relative from the test file location
163* targetname - the name name of the file when copied to the correct configuration location
164* process - optional process object to use for getting path location to copy to. Only needed if the Setup object call is not in the scope of the process object created with the MakeATSProcess(...) API.
165
166This function copies a given configuration file the location of a given trafficserver sandbox used in a test. Given a test might have more than on trafficserver instance, it can be difficult to understand the correct location to copy to. This function will deal with the details correctly.
167
168#### Examples
169
170Copy a file over
171
172```python
173ts1 = Test.MakeATSProcess("ts1",select_ports=False)
174# uses the setup object in the scope of the process object
175ts1.Setup.ts.CopyConfig('config/records_8090.config','records.config')
176```
177```python
178ts1 = Test.MakeATSProcess("ts1",select_ports=False)
179# uses the Setup in the global process via a variable passing
180Test.Setup.ts.CopyConfig('config/records_8090.config','records.config',ts1)
181# same as above, but uses the dynamic object model form
182Test.Setup.ts.CopyConfig('config/records_8090.config','records.config',Test.Processes.ts1)
183```
184
185## Setting up Origin Server
186### Test.MakeOriginServer(Name)
187 * name - A name for this instance of Origin Server.
188
189 This function returns a AuTest process object that launches the python-based microserver. Micro-Server is a mock server which responds to client http requests. Microserver needs to be setup for the tests that require an origin server behind ATS. The server reads a JSON-formatted data file that contains request headers and the corresponding response headers. Microserver responds with payload if the response header contains Content-Length or Transfer-Enconding specified.
190
191### addResponse(filename, request_header, response_header)
192* filename - name of the file where the request header and response header will be written to in JSON format
193* request_header - dictionary of request header
194* response_header - dictionary of response header corresponding to the request header.
195
196This function adds the request header and response header to a file which is then read by the microserver to populate request-response map. The key-fields required for the header dictionary are 'headers', 'timestamp' and 'body'.
197
198### Example
199```python
200#create the origin server process
201server=Test.MakeOriginServer("server")
202#define the request header and the desired response header
203request_header={"headers": "GET / HTTP/1.1\r\nHost: www.example.com\r\n\r\n", "timestamp": "1469733493.993", "body": ""}
204#desired response form the origin server
205response_header={"headers": "HTTP/1.1 200 OK\r\nConnection: close\r\n\r\n", "timestamp": "1469733493.993", "body": ""}
206#addResponse adds the transaction to a file which is used by the server
207server.addResponse("sessionlog.json", request_header, response_header)
208#add remap rule to traffic server
209ts.Disk.remap_config.AddLine(
210    'map http://www.example.com http://127.0.0.1:{0}'.format(server.Variables.Port)
211)
212```
213
214## Setting up DNS
215### Test.MakeDNServer(name, default=None)
216 * name - A name for this instance of the DNS.
217 * default - if a list argument is provided, uDNS will reply with the list contents instead of NXDOMAIN if a DNS can't be found for a partcular entry
218
219 This function returns a AuTest process object that launches the python-based microDNS (uDNS). uDNS is a mock DNS which responds to DNS queries. uDNS needs to be setup for the tests that require made-up domains. The server reads a JSON-formatted data file that contains mappings of domain to IP addresses. uDNS responds with the approriate IP addresses if the requested domain is in uDNS' mappings.
220
221 * addRecords(records=None, jsonFile=None)
222
223 This function adds records using either a dictionary, *records*, or a json file, *jsonFile*.
224
225 The supplied dictionary must be in the form of ```{ 'domain A': [IP1, IP2], 'domain B': [IP3, IP4] }```.
226
227 The supplied json file must take the form of
228 ```
229 {
230     "mappings": [
231         {domain A: [IP1, IP2]},
232         {domain B: [IP3, IP4]}
233     ]
234 }
235 ```
236
237 ### Examples
238 There are 3 ways to utilize uDNS -
239
240 Easy way if everything is done on localhost - by adding default option to Test.MakeDNServer:
241 *uDNS by default returns NXDOMAIN for any unknown mappings*
242
243 ```python
244    # create TrafficServer and uDNS processes
245    ts = Test.MakeATSProcess("ts")
246    dns = Test.MakeDNServer("dns", default=['127.0.0.1'])
247
248    ts.Disk.records_config.update({
249        'proxy.config.dns.nameservers': '127.0.0.1:{0}'.format(dns.Variables.Port), # let TrafficServer know where the DNS is located
250        'proxy.config.dns.resolv_conf': 'NULL',
251        'proxy.config.url_remap.remap_required': 0  # need this so TrafficServer won't return error upon not finding the domain in its remap file
252    })
253 ```
254
255 Using the *addRecords* method:
256 ```python
257    # create TrafficServer and uDNS processes
258    ts = Test.MakeATSProcess("ts")
259    dns = Test.MakeDNServer("dns")
260
261    ts.Disk.records_config.update({
262        'proxy.config.dns.nameservers': '127.0.0.1:{0}'.format(dns.Variables.Port), # let TrafficServer know where the DNS is located
263        'proxy.config.dns.resolv_conf': 'NULL',
264        'proxy.config.url_remap.remap_required': 0  # need this so TrafficServer won't return error upon not finding the domain in its remap file
265    })
266
267    dns.addRecords(records={"foo.com.":["127.0.0.1", "127.0.1.1"]})
268    # AND/OR
269    dns.addRecords(jsonFile="zone.json") # where zone.json is in the format described above
270 ```
271
272 Without disabling remap_required:
273 ```python
274    # create TrafficServer and uDNS processes
275    ts = Test.MakeATSProcess("ts")
276    dns = Test.MakeDNServer("dns")
277
278    ts.Disk.records_config.update({
279        'proxy.config.dns.resolv_conf': 'NULL',
280        'proxy.config.dns.nameservers': '127.0.0.1:{0}'.format(dns.Variables.Port) # let TrafficServer know where the DNS is located
281    })
282
283    # if we don't disable remap_required, we can also just remap a domain to a domain recognized by DNS
284    ts.Disk.remap_config.AddLine(
285        'map http://example.com http://foo.com'
286    )
287
288    dns.addRecords(records={"foo.com.":["127.0.0.1", "127.0.1.1"]})
289 ```
290
291## Condition Testing
292### Condition.HasATSFeature(feature)
293 * feature - The feature to test for
294
295 This function tests for Traffic server for possible feature it has been compiled with. Current Features you can test for are:
296 * TS_HAS_LIBZ
297 * TS_HAS_LZMA
298 * TS_HAS_JEMALLOC
299 * TS_HAS_TCMALLOC
300 * TS_HAS_IN6_IS_ADDR_UNSPECIFIED
301 * TS_HAS_BACKTRACE
302 * TS_HAS_PROFILER
303 * TS_USE_FAST_SDK
304 * TS_USE_DIAGS
305 * TS_USE_EPOLL
306 * TS_USE_KQUEUE
307 * TS_USE_PORT
308 * TS_USE_POSIX_CAP
309 * TS_USE_TPROXY
310 * TS_HAS_SO_MARK
311 * TS_HAS_IP_TOS
312 * TS_USE_HWLOC
313 * TS_USE_SET_RBIO
314 * TS_USE_LINUX_NATIVE_AIO
315 * TS_HAS_SO_PEERCRED
316 * TS_USE_REMOTE_UNWINDING
317 * TS_HAS_128BIT_CAS
318 * TS_HAS_TESTS
319 * TS_HAS_WCCP
320 * SPLIT_DNS
321
322### Example
323```python
324#create the origin server process
325Test.SkipUnless(
326    Condition.HasATSFeature('TS_USE_LINUX_NATIVE_AIO'),
327)
328```
329
330### Condition.HasCurlFeature(feature)
331 * feature - The feature to test for
332
333 This function tests for Curl for possible feature it has been compiled with. Consult Curl documenation for feature set.
334
335### Example
336```python
337#create the origin server process
338Test.SkipUnless(
339    Condition.HasCurlFeature('http2'),
340)
341```
342
343### Condition.PluginExists(pluginname)
344 * pluginname - The plugin to test for
345
346 This function tests for existence of a certain plugin in TrafficServer.
347
348### Example
349```python
350Test.SkipUnless(
351    Condition.PluginExists('a-plugin.so'),
352)
353```
354