深聊性能测试，从入门到放弃之：Locust性能自动化(五)API汇总整理(下)

1、HttpSession class

1.1 定义

定义解析：
----->>用于执行web请求和在请求之间保留 cookie的类。
记录每个请求，以便Locust可以显示统计信息。

这是python-reques的reques.Session 的扩展版，大多数情况下，工作原理都相同。

每次发送请求的方法带两个可选参数，这是locust的特性，并且这些参数在python-requests中是不存在的。

参数解析：
・ name ：可选，可以指定为在Locust的统计信息中用作标签，而不是URL路径。
・ catch_response ：可选布尔型参数，如果设置了该参数，则可用于发出请求，以返回上下文管理器以用作with语句的参数。
>>>>即使响应代码正常（2xx），也可以根据响应的内容将请求标记为失败。相反的方法也可行，即使没有响应代码（即500或404），也可以使用catch_response来捕获请求，然后将其标记为成功。

1.2 类及用法

①**init**

定义解析：
---->>初始化。

格式如下：

__init__(base_url，request_success，request_failure，* args，** kwargs)

②delete

定义解析：
---->>发送一个DELETE请求。返回Response对象。

格式如下：

delete（url，** kwargs）

参数解析：
・ url ：新Request对象的URL 。
・ kwargs ：可选参数。

返回类型：
・ requests.Response

③get

定义解析：
---->>发送get请求。返回Response对象。

格式如下：

get (url，** kwargs)

参数解析：
・ url ：新Request对象的URL 。
・ kwargs ：可选参数。

返回类型：
・ requests.Response

④head

定义解析：
---->>发送一个head请求。返回Response对象。

格式如下：

head (url，** kwargs)

参数解析：
・ url ：新Request对象的URL 。
・ kwargs ：可选参数。

返回类型：
・ requests.Response

⑤options

定义解析：
---->>发送一个options请求。返回Response对象。

格式如下：

options (url，** kwargs)

参数解析：
・ url ：新Request对象的URL 。
・ kwargs ：可选参数。

返回类型：
・ requests.Response

⑥patch

定义解析：
---->>发送一个patch请求。
返回Response对象。

格式如下：

options (url，data = None，** kwargs)

参数解析：
・ url ：新Request对象的URL 。
・ data ：可选，字典，元组列表，字节或文本文件等。
・ kwargs ：可选参数。

返回类型：
・ requests.Response

⑦post

定义解析：
---->>发送一个POST请求。返回Response对象。

格式如下：

post (url，data = None，json = None，** kwargs)

参数解析：
・ url ：新Request对象的URL 。
・ data ：可选字典，元组列表，字节或文本文件等。
・ json ：发送json格式。
・ kwargs ：可选参数。

返回类型：
・ requests.Response

⑧put

定义解析：
---->>发送一个PUT请求。
返回Response对象。

格式如下：

put (url，data = None，** kwargs)

参数解析：
・ url ：新Request对象的URL 。
・ data ：可选字典，元组列表，字节或文本文件等。
・ kwargs ：可选参数。

返回类型：
・ requests.Response

⑨request

定义解析：
---->>构造并发送requests.Reuqest。
返回requests.Response对象。

格式如下：

request (method，url，name = None，catch_response = False，** kwargs)

参数解析：
・ method ：新Request对象的方法 。
・ url ：新Request对象的URL 。
・ name ：可选，可以指定为在Locust的统计信息中用作标签，而不是URL路径。
・ catch_response ：可选布尔型参数，如果设置了该参数，则可用于发出请求，以返回上下文管理器以用作with语句的参数。
・ kwargs ：可选参数。
・ params ：可选，在查询字符串中发送的字典或字节请求数据。
・ data ：可选，发送的字典或字节请求数据。
・ head ：可选，发送的HTTP表头信息。
・ cookies ：可选，发送的CookieJar或Dict信息。
・ files ：可选，文件名，。
・ auth ：可选，认证信息。
・ timeout ：可选，超时时间，秒为单位。
・ allow_redirects ：可选，默认情况下设置为True。
・ proxies ：可选，字典到代理URL的映射协议。
・ stream ：可选，是否立即下载响应内容。默认为False。
・ verify ：可选，如果为True，将验证SSL证书。也可以提供CA_BUNDLE路径。
・ cert ：可选，如果为String，则为ssl客户端证书文件（.pem）的路径。如果是元组，（“证书”，“密钥”）配对。

2、Response class

2.1 定义

---->>该类位于python的request库中，用法发送HTTP请求的。

class Response

2.2 类及应用

①apparent_encoding

定义解析：
---->>由chardet库提供。

②close()

定义解析：
---->>关闭，一旦调用此方法，raw就不会再次访问基础对象。

③content

定义解析：
---->>响应内容，以字节为单位。

④cookies

定义解析：
---->>服务器发送的回的Cookie的CookieJar。

格式如下：

cookies = None

⑤elapsed

定义解析：
---->>从发送请求到响应到达之间经过的时间（以时间增量为单位）。
此属性专门测量发送请求的第一个字节与完成头解析之间所花费的时间。
因此，它不会因使用响应内容或stream关键字参数的值而受到影响。。

格式如下：

elapsed = None

⑥encoding

定义解析：
---->>访问r.text时进行编码以进行解码。

格式如下：

encoding = None

⑦headers

定义解析：
---->>不区分大小写的响应标题字典,俗称响应头的值。

格式如下：

headers= None

⑧history

定义解析：
---->>Response请求历史记录中的对象列表。
任何重定向响应都将在此处结束。
该列表从最早的请求到最新的请求进行排序。

格式如下：

history = None

⑨is_permanent_redirect

定义解析：
---->>如果此响应是重定向的永久版本之一，则为True。

⑩is_redirect

定义解析：
---->>如果此响应是格式正确的HTTP重定向，
并且可能已经被自动处理（由Session.resolve_redirects()），则为true 。

⑪iter_content

定义解析：
---->>遍历响应数据。
在请求上设置stream = True时，这避免了立即将内容读取到内存中以获得较大响应。大小是读入内存的字节数。

格式如下：

iter_content(chunk_size = 1，decode_unicode = False)

参数解析：
・ chunk_size ：必须为int或 None类型
・ decode_unicode ：默认为False，如果为True，将基于响应使用最佳可用编码对内容进行解码。

⑫iter_lines

定义解析：
---->>遍历响应数据，一次一行。
在请求上设置stream = True时，这避免了立即将内容读取到内存中以获得较大响应。

格式如下：

 iter_lines(chunk_size=512, decode_unicode=False, delimiter=None)

⑬json

定义解析：
---->>返回响应的json编码内容（如果有内容）。

格式如下：

json(**kwargs)

参数解析：
・ kwargs ：可选参数
・ ValueError ：返回值错误。

⑭raise_for_status()

定义解析：
---->>返回HTTPError。

⑮raw

定义解析：
---->>响应的类似文件的对象表现形式。
不适用于内部请求。

格式如下：

raw = None

⑯reason

定义解析：
---->>HTTP状态响应的原因。

格式如下：

reason = None

⑰request

定义解析：
---->>响应的对象。

格式如下：

request = None

⑱status_code

定义解析：
---->>响应的HTTP状态的整数代码。

格式如下：

status_code = None

⑲text

定义解析：
---->>响应的内容，以unicode表示。
如果Response.encoding为None，则使用chardet。

⑳URL

定义解析：
---->>响应的最终URL地址。

格式如下：

url = None

3、ResponseContextManager class

3.1 定义

class ResponseContextManager（response，request_success，request_failure）

---->>Response类还可以用作上下文管理器。
该类提供手动控制HTTP请求，在Locust统计信息为成功还是失败的能力。

状态有两个：success 和 failure

3.2 类及用法

①failure(exc）

定义解析：
---->>失败。
如果exc 是python内部的(例如字符串)，将在CatchResponseError中。

举个例子

# -*- coding: utf-8 -*-
"""
@ auth : carl_DJ
@ time : 2020-10-14
"""


with self.client.get("/", catch_response=True) as response:
    if response.content == b"":
        response.failure("No data")

②success()

定义解析：
---->>成功。

举个例子

# -*- coding: utf-8 -*-
"""
@ auth : carl_DJ
@ time : 2020-10-14
"""

with self.client.get("/does/not/exist", catch_response=True) as response:
    if response.status_code == 404:
        response.success()

4、Exceptions

4.1 exception InterruptTaskSet

exception InterruptTaskSet(reschedule=True)

定义解析：
---->>抛出任务时会中断用户的异常。

4.2 exception RescheduleTask

exception RescheduleTask

定义解析：
---->>在任务中，相当于return语句功能。
当不在TaskSet内部，则会移交给父TaskSet。

4.3 exception RescheduleTaskImmediately

exception RescheduleTaskImmediately

定义解析：
---->>当在用户任务中引发时，会立即重新调用另一个用户任务，（无需先调用wait_time）。

5、Environment class

5.1 定义

class Environment(*, user_classes=[], shape_class=None, tags=None, exclude_tags=None, events=None, host=None, reset_stats=False, stop_timeout=None, catch_exceptions=True, parsed_options=None)

5.2 类及应用

①catch_exceptions= True

定义解析：
---->>捕获正在运行中出现的异常，在 Web UI或者中控台中显示。

②create_local_runner（）

定义解析：
---->>创建一个local_runner 这个实例。

参数解析：
・ environment：环境实例

③create_master_runner

定义解析：
---->>创建一个master_runner这个实例。

格式如下：

create_master_runner（master_bind_host = '*'，master_bind_port = 5557）

参数解析：
・ master_bind_host ：需要连接的主服务器的地址，默认为“”，表示所有接口
・ master_bind_port ：需要连接的主服务器的端口号

④create_web_ui

定义解析：
---->>创建一个Web_UI这个实例，并运行。

格式如下：

create_web_ui(host='', port=8089, auth_credentials=None, tls_cert=None, tls_key=None, stats_csv_writer=None, delayed_start=False)

参数解析：
・ host ：Web服务器应接受其连接的主机/接口。默认为“”，表示所有接口
・ port ：监听端口号
・ auth_credentials ：基本身份认证
・ tls_cert – ：TLS证书路径，
・ tls_key ：TLS私钥可选路径
・ stats_csv_writer ：StatsCSV 实例
・ delay_start ：是否延迟启动web UI直到调用start（）

⑤create_worker_runner

定义解析：
---->>创建一个worker_runner这个实例。

格式如下：

create_worker_runner（master_host，master_port

参数解析：
・ master_host ：正在运行的主节点的主机/ IP
・ master_port ：主节点上要连接的端口

⑥events

定义解析：
---->>Locust内部使用的事件。
可以参考 本篇： 6、Event hooks

⑦exclude_tags

定义解析：
---->>如果设置，则仅执行此列表中未标记的任务。

格式如下：

exclude_tags= None

⑧host

定义解析：
---->>目标系统的 URL地址。

格式如下：

str = None

⑨parsed_options

定义解析：
---->>对已解析的命令行选项的可选引用（用于预填充Web UI中的字段)。

格式如下：

parsed_options= None

⑩process_exit_code

定义解析：
---->>若设置，则使Locust退出当前进程。

格式如下：

process_exit_code：int= None

⑪reset_stats

定义解析：
---->>确定在生成所有模拟用户后是否应重置统计信息。

格式如下：

reset_stats= False

⑫runner

定义解析：
---->>若设置，则使Locust退出当前进程。

格式如下：

 locust.runners.Runner= None

⑬shape_class

定义解析：
---->>控制负载测试的形态类。

格式如下：

locust.shape.LoadTestShape = None

⑭stats

定义解析：
---->>引用RequestStats实例。

格式如下：

locust.stats.RequestStats = None

⑮stop_timeout

定义解析：
---->>设置等待超时时间，超过时间后，将会终止进程。

格式如下：

stop_timeout = None

⑯tags

定义解析：
---->>若设置，则仅执行由该列表中的标签标记的任务。

格式如下：

tags = None

⑰user_classes

定义解析：
---->>运行程序的 user类。

格式如下：

list[locust.user.users.User] = []

⑱web_ui

定义解析：
---->>对web_ui实例的引用。

格式如下：

locust.web.WebUI = None

6、Event hooks

6.1 class Events

①init

定义解析：
---->>一旦创建了Environment实例和locust运行器实例后，在启动Locust时触发。最终用户的代码可以使用此挂钩来运行需要访问环境的代码。例如，将侦听器注册到request_success，request_failure或其他事件。

参数解析：
・environment：环境实例

②init_command_line_parser

定义解析：
---->>可用于将命令行选项添加到Locust事件中。

参数解析：
・parser：解析器，来运行 ArgumentParser 实例

③quitting

定义解析：
---->>Locust退出进程时，触发此动作。

参数解析：
・environment ：环境实例

④report_to_master

定义解析：
---->>在worker状态下运行时才被调用。
可以将数据定期发送到主服务器的字典上，同时会定期触发把报告发送到服务器的动作。

注意：在"stats"和"errors"这两个状态，不需要触发这个动作

参数解析：
・client_id ：正在运行的客户端 ID
・data: 可发送到主数据库的数据的字典

⑤request_failure

定义解析：
---->>请求失败时触发。

参数解析：
・request_type ：请求类型
・response_time：引发异常请求时间(单位：毫秒)
・response_length ：响应内容长度
・exception：抛出异常实例
・name：调用URL的路径

⑥request_success

定义解析：
---->>请求成功完成时触发。

参数解析：
・request_type ：请求类型
・response_time：引发异常请求时间(单位：毫秒)
・response_length ：响应内容长度
・name：调用URL的路径

⑦reset_stats

定义解析：
---->>在Web UI中 “重置统计信息” 的按钮。

⑧spawning_complete

定义解析：
---->>产生所有模拟用户时触发。

参数解析：
・user_count ：用户数

⑨test_start

定义解析：
---->>负载测试开始。
如果用户数量在测试期间更改，则不会再次触发；
如果运行Locust分布式时，仅在主节点上而不在每个辅助节点上触发该事件。

⑩test_stop

定义解析：
---->>测试停止。
仅在主节点而非每个子节点上触发该事件。

⑪user_error

定义解析：
---->>User类异常是触发。

参数解析：
・user_instance ：异常的用户类实例
・exception：抛出异常实例
・tb：追溯对象（来自e .__ traceback__）

⑫worker_report

定义解析：
---->>在master模式下运行是使用。
当主服务器从worker服务器接收报告时会触发此事件。

参数解析：
・client_id ：正在运行的客户端 ID
・data: 带有工作节点数据的 数据字典

6.2 class EventHook

class EventHook

这是简单事件类，同样为Locust中不同类型的事件提供Hook。

举个例子

# -*- coding: utf-8 -*-
"""
@ auth : carl_DJ
@ time : 2020-10-14
"""

#设置事件为EvnentHook
my_event = EventHook()

def on_my_event(a,b,**kw):
	#print("Event was fired with arguments: %s, %s" % (a, b))
	print(f"Event wa fired with arguments :{a},{b}")

#在事件添加监听器
my_event.add_listener(on_my_enent)
my_event.fire(a="foo", b="bar")
	

7、Runner classes

7.1 class Runner

7.1.1 定义

定义解析
---->>通过启动和停止用户来进行负载测试。
在Environment 实例上使用这三个create_local_runner, create_master_runner或者 create_worker_runner 其中的一种来创建所需要的运行器。

格式如下

class Runner(environment)

7.1.2 类及用法

①quit
---->>停止或者直接终止任务在运行的程序。

②start(user_count, spawn_rate, wait=False)

---->>开始运行。

参数解析
・user_count： 启动用户数
・spawn_rate：每秒产生用户数
・wait：True，等待产生所有用户数，(相当于集合点)；False(默认)，会启动生成用户的绿色按钮，并且对该方法的调用将进行返回。

③stop()
---->>通过停止所有正在运行的用户来停止正在运行的负载测试.

7.2 class MasterRunner

7.2.1 定义

定义解析

① 用于跨多个进程/机器进行分布式负载测试；

②Master Runner 本身不会产生任何用户行为，相反，它希望Worker Runner连接到它，然后它将引导启动和停止用户行为，对Worker Runner返回的信息进行汇总。

格式如下

class MasterRunner(environment, master_bind_host, master_bind_port)

7.3 class LocalRunner

7.31 定义

定义解析
---->> 运行单个进程负载测试的运行程序。

格式如下

class LocalRunner(environment)

7.4 class WorkerRunner

7.4.1 定义

定义解析
①用于跨多个进程/机器进行分布式负载测试；

②WorkerRunner连接到MasterRunner，它将从中接收启动和停止用户行为的说明；

③WorkerRunner将定期获取正在运行的用户生成的统计信息，并将其发送回MasterRunner。

格式如下

class WorkerRunner(environment, master_host, master_port)

8、Web UI class

8.1 定义

定义解析
---->> 运行一个 Flask 网站，可以使用environment.runner，并且可以在environment.stats中显示负载测试统计信息。

格式如下

class WebUI(environment, host, port, auth_credentials=None, tls_cert=None, tls_key=None, stats_csv_writer=None, delayed_start=False)

8.2 类及用法

① app= None
对flask.Flask 应用程序的引用。可用于以其他各种方式添加其他网络路线和自定义Flask应用。

举个例子

# -*- coding: utf-8 -*-
"""
@ auth : carl_DJ
@ time : 2020-10-14
"""

from flask import request

#设置路由
@web_ui.app.route("/my_custom_route")

def my_custom_route():
    return "your IP is: %s" % request.remote_addr
    

这里说一下，如果不知道 Flask，可以参照小鱼这篇博文：
《Python3，网站搭建之构建Flask项目，带你启动web服务！ ！》

看完这篇，保证明明白白的。

②auth_required_if_enabled(view_func)

---->>在自定义路由器方法上使用装饰器，如果使用web-auth标识，
则将会进行身份认证。

上例子：

# -*- coding: utf-8 -*-
"""
@ auth : carl_DJ
@ time : 2020-10-14
"""

#设置路由
@web_ui.app.route("/my_custom_route")
#开启auth认证
@web_ui.auth_required_if_enabled

def my_custom_route():
    return "custom response"
    

③greenlet= None

---->>正在运行的web服务器

④server= None

---->> 引用pyqsgi.WSGIServer 实例

⑤stop()

---->> 停止运行 web服务器

⑥template_args: dict= None

---->>用于呈现Web UI的index.html的参数。必须与扩展的index.html的自定义模块一起使用。

9、总结

到这里， 关于Locust的API内容，已经完成了。
是不是也松了一口气，想说一句：挖草~ ~ 我终于看到最后了。

其实，小鱼在写到这里，也发出同样的感叹：唉我去了~~ 两点了！！！

然后嘞… 额… 你懂得 ~ ~

同样，在文章的结尾，小鱼再把Locust的所有文章列出来，方便各位阅读！！

第一章，初识Locust

《深聊性能测试，从入门到放弃之：Locust性能自动化(一)初识Locust》

第二章，代码实战

《深聊性能测试，从入门到放弃之：Locust性能自动化(二)代码实战》

第三章，提高Locust性能

《深聊性能测试，从入门到放弃之：Locust性能自动化(三)如何提高Locust性能》

第四章，自定义客户端测试

《深聊性能测试，从入门到放弃之：Locust性能自动化(四)自定义客户端测试》

第五章，API汇总整理

《深聊性能测试，从入门到放弃之：Locust性能自动化(五)API汇总整理(上)》

《深聊性能测试，从入门到放弃之：Locust性能自动化(五)API汇总整理(下)》