This 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.
The current layout is:
gold_tests/ - contains all the tests that run on the Reusable Gold Testing System (AuTest)
tools/ - contains programs used to help with testing.
include/ - contains headers used for unit testing.
To help with easy running of the tests, there is autest.sh and bootstrap.py.
This 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.
This 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.
This file is used to setup a virtual environment using pipenv. It contains information including the packages needed for Autest. A set of commands for pipenv:
-d option to install dev packages )AuTest 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.
To run autest manually, the recommended way is to follow these steps:
AuTest 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.
When writing for the AuTest system please refer to the current Online Documentation for general use of the system. To use CurlHeader tester for testing output of curl, please refer to CurlHeader README
Autest 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.6 or better is used. There is also a new command line argumented added specifically for Trafficserver:
--ats-bin < path to bin directory >
This 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.
This 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.
The 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.
# Define default ATS ts=Test.MakeATSProcess("ts") # Call traffic_ctrl to set new generation tr=Test.AddTestRun() tr.Processes.Default.Command='traffic_ctl' tr.Processes.Default.ReturnCode=0 # set the environment for traffic_control to run in to be the same as the "ts" ATS instance tr.Processes.Default.Env=ts.Env
These are the current variables that are defined dynamically for Trafficserver
port - the ipv4 port to listen on portv6 - the ipv6 port to listen on admin_port - the admin port used. This is set even is select_port is False
A 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:
Create a server
# don't set ports because a config file will set them ts1 = Test.MakeATSProcess("ts1",select_ports=False) ts1.Setup.ts.CopyConfig('config/records_8090.config','records.config')
Create a server and get the dynamic port value
# Define default ATS ts=Test.MakeATSProcess("ts") #first test is a miss for default tr=Test.AddTestRun() # get port for command from Variables tr.Processes.Default.Command='curl "http://127.0.0.1:{0}" --verbose'.format(ts.Variables.port)
Add value to a configuration file
# setup some config file for this server ts.Disk.records_config.update({ 'proxy.config.body_factory.enable_customizations': 3, # enable domain specific body factory 'proxy.config.http.cache.generation':-1, # Start with cache turned off 'proxy.config.config_update_interval_ms':1, }) ts.Disk.plugin_config.AddLine('xdebug.so') ts.Disk.remap_config.AddLines([ 'map /default/ http://127.0.0.1/ @plugin=generator.so', #line 2 'map /generation1/ http://127.0.0.1/' + ' @plugin=conf_remap.so @pparam=proxy.config.http.cache.generation=1' + ' @plugin=generator.so', #line 3 'map /generation2/ http://127.0.0.1/' + ' @plugin=conf_remap.so @pparam=proxy.config.http.cache.generation=2' + ' @plugin=generator.so' ])
This 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.
Copy a file over
ts1 = Test.MakeATSProcess("ts1",select_ports=False) # uses the setup object in the scope of the process object ts1.Setup.ts.CopyConfig('config/records_8090.config','records.config')
ts1 = Test.MakeATSProcess("ts1",select_ports=False) # uses the Setup in the global process via a variable passing Test.Setup.ts.CopyConfig('config/records_8090.config','records.config',ts1) # same as above, but uses the dynamic object model form Test.Setup.ts.CopyConfig('config/records_8090.config','records.config',Test.Processes.ts1)
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.
This 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’.
#create the origin server process server=Test.MakeOriginServer("server") #define the request header and the desired response header request_header={"headers": "GET / HTTP/1.1\r\nHost: www.example.com\r\n\r\n", "timestamp": "1469733493.993", "body": ""} #desired response form the origin server response_header={"headers": "HTTP/1.1 200 OK\r\nConnection: close\r\n\r\n", "timestamp": "1469733493.993", "body": ""} #addResponse adds the transaction to a file which is used by the server server.addResponse("sessionlog.json", request_header, response_header) #add remap rule to traffic server ts.Disk.remap_config.AddLine( 'map http://www.example.com http://127.0.0.1:{0}'.format(server.Variables.Port) )
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.
This function adds records using either a dictionary, records, or a json file, jsonFile.
The supplied dictionary must be in the form of { 'domain A': [IP1, IP2], 'domain B': [IP3, IP4] }.
The supplied json file must take the form of
{
"mappings": [
{domain A: [IP1, IP2]},
{domain B: [IP3, IP4]}
]
}
There are 3 ways to utilize uDNS -
Easy way if everything is done on localhost - by adding default option to Test.MakeDNServer: uDNS by default returns NXDOMAIN for any unknown mappings
# create TrafficServer and uDNS processes ts = Test.MakeATSProcess("ts") dns = Test.MakeDNServer("dns", default=['127.0.0.1']) ts.Disk.records_config.update({ 'proxy.config.dns.nameservers': '127.0.0.1:{0}'.format(dns.Variables.Port), # let TrafficServer know where the DNS is located 'proxy.config.dns.resolv_conf': 'NULL', 'proxy.config.url_remap.remap_required': 0 # need this so TrafficServer won't return error upon not finding the domain in its remap file })
Using the addRecords method:
# create TrafficServer and uDNS processes ts = Test.MakeATSProcess("ts") dns = Test.MakeDNServer("dns") ts.Disk.records_config.update({ 'proxy.config.dns.nameservers': '127.0.0.1:{0}'.format(dns.Variables.Port), # let TrafficServer know where the DNS is located 'proxy.config.dns.resolv_conf': 'NULL', 'proxy.config.url_remap.remap_required': 0 # need this so TrafficServer won't return error upon not finding the domain in its remap file }) dns.addRecords(records={"foo.com.":["127.0.0.1", "127.0.1.1"]}) # AND/OR dns.addRecords(jsonFile="zone.json") # where zone.json is in the format described above
Without disabling remap_required:
# create TrafficServer and uDNS processes ts = Test.MakeATSProcess("ts") dns = Test.MakeDNServer("dns") ts.Disk.records_config.update({ 'proxy.config.dns.resolv_conf': 'NULL', 'proxy.config.dns.nameservers': '127.0.0.1:{0}'.format(dns.Variables.Port) # let TrafficServer know where the DNS is located }) # if we don't disable remap_required, we can also just remap a domain to a domain recognized by DNS ts.Disk.remap_config.AddLine( 'map http://example.com http://foo.com' ) dns.addRecords(records={"foo.com.":["127.0.0.1", "127.0.1.1"]})
This function tests for Traffic server for possible feature it has been compiled with. Current Features you can test for are:
#create the origin server process Test.SkipUnless( Condition.HasATSFeature('TS_USE_LINUX_NATIVE_AIO'), )
This function tests for Curl for possible feature it has been compiled with. Consult Curl documenation for feature set.
#create the origin server process Test.SkipUnless( Condition.HasCurlFeature('http2'), )
This function tests for existence of a certain plugin in TrafficServer.
Test.SkipUnless( Condition.PluginExists('a-plugin.so'), )