阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

      插件 jQuery.mockjax 中文API文档

      插件 jQuery.mockjax 中文API文档

      源码 & 下载

      适用场景

      插件特点

      jQuery Mockjax插件提供了一个简单且极其灵活的界面,用于模拟或模拟ajax请求和响应

      基本文档

      API方法

      Mockjax只包含几种方法,每种方法都列在下面。您将在下面的部分中找到大量示例,但如果您正在寻找特定选项,请查看此列表:

      • Number $.mockjax(/* Object */ options)
        • 为匹配的请求设置mockjax处理程序
        • 返回该处理程序的索引,可用于清除各个处理程序
        • options:[Object]定义用于模拟请求的设置
          • url:[String | RegExp]指定应模拟数据的请求的url。如果它是一个字符串并包含任何星号(),则通过转换为正则表达式将它们视为通配符。任何将被替换.+。如果您遇到此快捷方式的问题,请切换到使用完整的正则表达式而不是字符串和星号组合
          • data:[Object| Function ] 除了URL,匹配参数
          • type:[String]指定要匹配的HTTP方法,通常是GET或POST。不区分大小写的,所以get和post也行
          • headers:[Object]密钥将被模拟为服务器为请求返回的附加标头(注意:这不用于匹配请求标头!)
          • status:[Number]一个整数,指定有效的服务器响应代码。这模拟了服务器响应代码
          • statusText:[String]指定有效的服务器响应代码说明。这模拟了服务器响应代码描述
          • responseTime:[Number]一个整数,指定模拟的网络和服务器延迟(以毫秒为单位)。默认是500。将此设置为0最小化模拟延迟
          • isTimeout:[Boolean]确定模拟是否会强制请求超时
          • contentType:[String]指定响应的内容类型
          • response:[Function]接受请求设置并允许在每次请求时动态设置响应设置(包括响应正文)的功能(请参阅下面的示例)
          • responseText:[String]为请求指定模拟文本或模拟对象文字
          • responseXML:[String]指定请求的模拟XML
          • proxy:[String]指定文件的路径,从该文件返回请求的内容
          • lastModified:[String]一个日期字符串,指定请求的模拟上次修改时间。这用于$.ajax确定自上次请求以来所请求的数据是否是新的
          • etag:[String]指定引用所请求数据的特定版本的唯一标识符。这用于$.ajax确定自上次请求以来所请求的数据是否是新的。(见HTTP_ETag)
          • onAfterSuccess:[Function]在调用success方法后调用的回调,这对于在调用完成后检查条件很有用
          • onAfterError:[Function]调用错误方法后将调用的回调,这对于在调用完成后检查条件很有用
          • onAfterComplete:[Function]类似于onAfterSuccess,但将在调用完整方法后执行
      • Object $.mockjax.handler(/* Number */ id)
        • 使用提供的函数返回处理程序的模拟请求设置id。这里要小心,你正在访问插件的内部工作,对这个对象的任何更改都可能很糟糕。
      • Array $.mockjax.handlers()
        • 返回模拟处理程序的数组。注意:清除处理程序时,不会修改此数组,清除的处理程序位置只需设置为null。因此,阵列长度仅在添加新模拟时才会更改。在这里要小心,你正在访问插件的内部工作,对数组的任何更改都可能非常糟糕。
      • void $.mockjax.clear([/* Number */ id])
        • 如果id提供了,则清除具有该ID的处理程序(即,匹配它的请求将不再这样做,处理程序被完全删除)
        • 如果未id提供,则清除所有处理程序,将Mockjax重置为其初始状态
      • Array<Object> $.mockjax.mockedAjaxCalls()
        • 返回所有模拟的ajax调用的数组,每个条目都是传递给$.mockjax()函数的请求设置对象
        • 如果 $.mockjaxSettings.retainAjaxCalls设置为false,则它将始终为空
      • Array<Object> $.mockjax.unfiredHandlers()
        • 返回尚未使用的所有模拟处理程序设置的数组。换句话说,如果处理程序已用于$.ajax()调用,则它不会出现在此数组中
      • Array<Object> $.mockjax.unmockedAjaxCalls()
        • 返回所有未模拟的Ajax调用的数组。该数组包含传入的设置对象$.ajax({...})
        • 如果$.mockjaxSettings.retainAjaxCalls设置为false,则它将始终为空
      • void $.mockjax.clearRetainedAjaxCalls()
        • 清空返回的阵列$.mockjax.mockedAjaxCalls$.mockjax.unmockedAjaxCalls

      概述:你的第一个模拟

      我们的第一个例子是针对一个幸运应用程序的简单REST服务,其中REST端点/restful/fortune返回以下JSON消息:

      {
          "status": "success",
          "fortune" : "Are you a turtle?"
      }
      

      为了将财富投入到我们的页面中,我们将使用以下HTML和jQuery代码:

      <!DOCTYPE html>
      <html>
        <head>
          <title>Fortune App</title>
          <script src="http://code.jquery.com/jquery-1.11.1.min.js"></script>
        </head>
      <body>
        <div id="fortune"></div>
      </body>
      </html>
      
      $.getJSON("/restful/fortune", function(response) {
        if ( response.status == "success") {
          $("#fortune").html( "Your fortune is: " + response.fortune );
        } else {
          $("#fortune").html( "Things do not look good, no fortune was told" );
        }
      });
      

      此时如果我们要运行此代码,它将失败,因为尚未实现REST服务。这就是Mockjax插件的好处开始得到回报的地方。使用Mockjax的第一步是通过添加常规脚本标记来包含插件:

      <head>
        ...
        <script src="vendor/jquery.mockjax.js"></script>
      </head>
      

      一旦包含了这些内容,您就可以开始拦截Ajax请求并模拟响应。所以让我们通过包含以下代码来模拟服务:

      $.mockjax({
        url: "/restful/fortune",
        responseText: {
          status: "success",
          fortune: "Are you a mock turtle?"
        }
      });
      

      定义内联的JSON字符串需要一个JSON.stringify()方法可用。对于某些浏览器,您可能需要包含 json2.js,它包含在lib文件夹中。但是,您也可以在responseText 属性中简单地提供已经字符串化的JSON版本。

      如果您计划模拟xml响应,则可能还必须包含 jquery.xmldom.js,也可以在lib文件夹中找到。

      Mockjax深度

      此时Mockjax所做的是$.ajax()用一个透明地检查所请求的URL的包装器替换该方法。如果URL与定义的URL匹配$.mockjax(),则它会拦截请求并XMLHttpRequest在执行jQuery.ajax()处理程序之前设置模拟对象 。否则,请求将返回到本机$.ajax()方法以进行正常执行。这个实现细节的一个好处是通过模拟XMLHttpRequest对象,插件继续使用jQuery的本机ajax处理,因此不需要实现自定义Ajax工作流。

      在编写模拟响应的代码时,生成代码不需要修改这一事实具有很大的价值。模拟可以透明地插入。通过构建框架包含插件和模拟定义,这可以轻松集成到大多数框架中。通过侦听查询字符串标志并注入插件和定义,也可以在运行时包含它。

      现在让我们看一下定义插件提供的模拟的各种方法。以下部分概述了Mockjax的灵活性并创建了响应。

      可用于模拟的数据类型 jQuery是能够处理和分析Text,HTML,JSON,JSONP, Script和XML数据格式和Mockjax能够嘲笑任何这些格式。有两点需要注意:取决于你如何模拟JSON, JSONP你可能需要 为方法包含json2.jsJSON.stringify()(通常只包括旧浏览器)。此外,如果您模拟XML内联,则需要包含将xmlDOM XML字符串转换为DOM对象的插件。但是,如果您使用下面概述的代理方法,那么在任何情况下都不需要包含JSON或XMLDOM插件。

      详细的请求和响应定义

      定义匹配请求

      模拟请求时,您需要做的第一件事是定义拦截和模拟的URL端点。与上面的示例一样,这可以是一个简单的字符串:

      $.mockjax({
        url: "/url/to/rest-service"
      });
      

      或包含*一个通配符:

      $.mockjax({
        // Matches /data/quote, /data/tweet etc.
        url: "/data/*"
      });
      

      或完整的正则表达式:

      $.mockjax({
        // Matches /data/quote, /data/tweet but not /data/quotes
        url: /^\/data\/(quote|tweet)$/i
      });
      

      除了url之外,您还可以匹配数据选项:

      $.mockjax({
        url:  "/rest",
        data: { action: "foo" }
      });
      

      该数据选择可能是一个自定义的匹配函数返回true的false 数据是否预期或不:

      $.mockjax({
        url: "/rest",
        data: function( data ) {
          return deepEqual( data, expected );
        }
      });
      

      数据函数是断言的推荐位置。返回true并让选择的测试框架完成剩下的工作:

      $.mockjax({
        url: "/rest",
        data: function ( json ) {
          assert.deepEqual( JSON.parse(json), expected ); // QUnit example.
          return true;
        }
      });
      

      要捕获URL参数,请使用URL的捕获正则表达式和urlParams数组来指示通常将捕获的参数的名称:

      $.mockjax({
        // matches /author/{any number here}/isbn/{any number with dashes here}
        // for example: "/author/1234/isbn/1234-5678-9012-0"
        url: /^\/author\/([\d]+)\/isbn\/([\d\-]+)$/,
        // names of matching params
        urlParams: ["authorID", "isbnNumber"],
        response: function (settings) {
          var authorID = settings.urlParams.authorID;
          var isbnNumber = settings.urlParams.isbnNumber;
          // etc...
        }
      });
      

      定义多个请求

      从版本2.2开始,允许一次定义多个请求。 $.mockjax([…])返回处理程序索引的数组。可以通过索引重置处理程序。阅读删除Mockjax处理程序的更多内容。

      var handlers = $.mockjax([
        {url: '/rest', responseText: 'one'},
        {url: '/rest', responseText: 'two'}
      ]);
      
      $.mockjax.clear(handlers[0]);
      

      定义响应

      第二步是定义响应的类型和内容。您将要处理的两个主要属性是responseText或 responseXML。这些属性镜像XMLHttpRequest 在实时响应期间设置的本机对象属性。指定响应有三种不同的模式:内联,代理和回调。

      内联响应

      一个简单的文本响应是:

      $.mockjax({
        url: "/restful/api",
        responseText: "A text response from the server"
      });
      

      一个简单的JSON响应是:

      $.mockjax({
        url: "/restful/api",
        // You may need to include the [json2.js](https://raw.github.com/douglascrockford/JSON-js/master/json2.js) library for older browsers
        responseText: { "foo": "bar" }
      });
      

      另请注意,JSON响应实际上只是一个文本响应,jQuery将为您解析为JSON(并将JSON对象返回给success和complete 回调)。

      一个简单的XML响应是:

      $.mockjax({
        url: "/restful/api",
        // Need to include the xmlDOM plugin to have this translated into a DOM object
        responseXML: "<document><quote>Hello world!</quote></document>"
      });
      

      正如您所看到的,如果您有大量数据被嘲笑,这将变得难以处理。这样就把我们带到了下一个模式:代理。

      Proxy

      在下面的示例中,Mockjax插件将拦截请求 /restful/api并将其重定向到/mocks/data.json:

      $.mockjax({
        url: "/restful/api",
        proxy: "/mocks/data.json"
      });
      

      该/mocks/data.json文件可以包含您想要的任何有效JSON内容,并允许您将该模拟数据保存在自己的文件中以实现可维护性。

      注意:如果您使用poxy测试代码,最好为测试运行实际的Web服务器。只需test/index.html从文件系统加载可能导致代理文件无法正确加载。我们建议使用像http-servernpm模块这样的东西。

      Callback

      在最后的响应模式,我们可以定义在一个回调函数 response性质,并将它设置responseText或responseXML根据需要:

      $.mockjax({
        url: "/restful/api",
        response: function(settings) {
          // Investigate the `settings` to determine the response...
      
          this.responseText = "Hello world!";
        }
      });
      

      此回调的默认版本是同步的。如果为回调函数提供这两个参数,则可以使用异步代码设置动态响应。

      $.mockjax({
        url: '/restful/api',
        response: function(settings, done) {
          var self = this;
          someAsyncMethod(function(data){
            self.responseText = data;
            done();
          });
        }
      });
      

      请注意,回调给出了$.mockjax({…}) 与jQuery或您的应用程序定义的任何Ajax设置合并的方法提供的设置。这允许您在设置响应正文(或标题)之前彻底调查请求。

      先进的模拟技术

      在这一点上,我们已经了解了Mockjax的一系列基本模拟技术,现在将解压缩插件中包含的一些其他功能。

      模拟响应时间和延迟

      模拟模拟的网络和服务器延迟就像responseTime在模拟定义中添加属性一样简单:

      $.mockjax({
        url: "/restful/api",
        // Simulate a network latency of 750ms
        responseTime: 750,
        responseText: "A text response from the server"
      });
      

      您还可以使用间隔responseTime来随机化延迟:

      $.mockjax({
        url: "/restful/api",
        // Use a random value between 250ms and 750ms
        responseTime: [250, 750],
        responseText: "A text response from the server"
      });
      

      模拟HTTP响应状态

      通过简单地添加status属性,也可以模拟200以外的响应状态(默认为Mockjax)。

      $.mockjax({
        url: "/restful/api",
        // Server 500 error occurred
        status: 500,
        responseText: "A text response from the server"
      });
      

      能够提供一系列可能的响应状态(从中随机选择给定请求的响应):

      // Randomly fail
      $.mockjax({
        url: "/restful/api",
        status: [200,400,500]
      });
      
      // Randomly fail (with a preference towards success)
      $.mockjax({
        url: "/restful/api",
        status: [200,400,200,500,200]
      });
      

      这些强制错误状态代码将被处理,就像服务器返回错误一样:error回调将使用正确的参数执行。

      设置 Content-Type

      您可以设置内容类型以与模拟响应关联,在​​下面的示例中,我们将设置JSON内容类型。

      $.mockjax({
        url: "/restful/api",
        contentType: "application/json",
        responseText: {
          hello: "World!"
        }
      });
      

      设置其他HTTP响应标头

      可以通过在头对象文字中设置密钥来提供其他HTTP响应头:

      $.mockjax({
        url: "/restful/api",
        contentType: "application/json",
        responseText: {
          hello: "World!"
        },
        headers: {
          etag: "xyz123"
        }
      });
      

      动态生成模拟定义

      在某些情况下,所有REST调用都基于URL架构。Mockjax可以指定一个回复函数,该函数可以处理$.ajax请求设置。然后,回调函数可以返回false以允许本地处理请求,或者返回具有相关Mockjax参数集的对象文字。下面是一个重写所有Ajax请求以代理静态模拟的示例:

      $.mockjax(function(settings) {
      
      // settings.url might be: "/restful/<service>" such as "/restful/user"
      
          var service = settings.url.match(/\/restful\/(.*)$/);
          if ( service ) {
              return {
                  proxy: "/mocks/" + service[1] + ".json"
              };
          }
          // If you get here, there was no url match
          return;
      });
      

      访问请求标头

      在某些情况下,您可能需要访问请求标头以确定匹配或响应主体。为此,您需要指定一个处理$.ajax请求设置的回调函数:

      $.mockjax(function( requestSettings ) {
        // Here is our manual URL matching...
        if ( requestSettings.url === "/restful/user" ) {
          // We have a match, so we return a response callback...
          return {
            response: function( origSettings ) {
      
            	// now we check the request headers, which may be set directly
            	// on the xhr object through an ajaxSetup() call or otherwise:
      
            	if ( requestSettings.headers["Authentication"] === "some-token" ) {
            	  this.responseText = { user: { id: 13 } };
            	} else {
        		  this.status = 403;
        		  this.responseText = "You are not authorized";
              }
            }
          };
        }
        // If you get here, there was no url match
        return;
      });
      

      强制模拟服务器超时

      由于Mockjax的实现方式,它利用了jQuery对请求的内部超时处理。但是,如果您想强制请求超时,可以通过将isTimeout 属性设置为true来执行此操作:

      $.mockjax({
        url: '/restful/api',
        responseTime: 1000,
        isTimeout: true
      });
      

      动态生成模拟响应

      通过在response参数上实现回调函数,还可以在每个请求时动态生成响应文本:

      $.mockjax({
        url: "/restful/webservice",
        dataType: "json",
        response: function(settings) {
          this.responseText = {
            randomText: "random " + Math.random()
          };
        }
      });
      

      数据类型

      上面的许多例子都嘲笑了一个json回应。你也可以模仿xml:

      $.mockjax({
        url: "/some/xml",
        dataType: "xml",
        responseXML: "<document><say>Hello world XML</say></document>"
      });
      

      (不要忘记,你可能也需要xmlDOM图书馆!)

      而且html:

      $.mockjax({
        url: "/some/webservice",
        dataType: "html",
        responseText: "<div>Hello there</div>"
      });
      

      请求完成后执行操作

      如果您需要在呼叫完成后执行某些操作,则可以使用其中一个onAfter{Xxxxx}选项。例如,要在请求完成时(成功或不成功)触发方法:

      $.mockjax({
        url: "/api/end/point",
        onAfterComplete: function() {
          // do any required cleanup
        }
      });
      

      全局定义Mockjax设置

      也可以通过覆盖$.mockjaxSettings对象来定义所有Mockjax请求的全局默认值。默认情况下,设置如下:

      {
        log:             null,  // DEPRECATED, use $.mockjaxSettings.logger instead
        logger:          window.console,
        logging:         2,
        logLevelMethods: ['error', 'warn', 'info', 'log', 'debug'],
        namespace:       null,
        status:          200,
        statusText:      "OK",
        responseTime:    500,
        isTimeout:       false,
        throwUnmocked:   false,
        retainAjaxCalls: true,
        contentType:     "text/plain",
        response:        "",
        responseText:    "",
        responseXML:     "",
        proxy:           "",
        proxyType:       "GET",
        lastModified:    null,
        etag:            "",
        headers: {
          etag: "IJF@H#@923uf8023hFO@I#H#",
          "content-type" : "text/plain"
        }
      }
      

      要覆盖特定设置(如默认设置)content-type,您将执行以下操作:

      $.mockjaxSettings.contentType = "application/json";
      

      设置全局URL命名空间

      命名空间选项$.mockjaxSettings允许您将前缀应用于所有模拟的URL,例如/api/v1。

      $.mockjaxSettings.namespace = "/api/v1";
      

      然后以下模拟将匹配 /api/v1/rest

      $.mockjax({
          url: "/rest"
      })
      

      全局命名空间选项也可以在特定的模拟上覆盖。

      $.mockjax({
          url: "/rest-2",
          namespace: null
      })
      

      请注意,名称空间前缀不适用于代理。

      全球定义匹配顺序

      默认情况下,Mockjax按注册顺序匹配请求(mockjax认为在最后注册的处理程序之前首先注册的处理程序)。要扭转此行为:

      $.mockjaxSettings.matchInRegistrationOrder = false;

      设置matchInRegistrationOrder以false使您可以覆盖以前定义的处理程序。假设你有:

      $.mockjax({
          url: "/rest",
          responseText: "hello"
      });
      $.mockjax({
          url: "/rest",
          responseText: "byebye"
      });
      

      默认行为是Mockjax返回"hello",但是matchInRegistrationOrder 设置为false,Mockjax将返回"byebye"。

      此行为允许您在最初设置后覆盖旧处理程序。

      删除Mockjax处理程序

      如果您需要重置已添加的Mockjax处理程序,只需调用即可 $.mockjax.clear()。这不会重置$.mockjaxSettings!

      $.mockjax.clear();

      您还可以使用其ID清除单个模拟处理程序:

      var id = $.mockjax({
         ...
      });
      
      $.mockjax.clear(id);
      

      杂项信息

      jQuery版本支持

      我们努力确保Mockjax在jQuery的所有次要(和主要)版本的最远补丁版本上进行测试,从1.5.2开始一直到3.x. 换句话说,我们不测试1.6.1,而是测试1.6.4(1.6.x线上最远的补丁版本)。/test目录中的QUnit测试包括指向标题中测试的每个jQuery版本的链接。

      浏览器测试

      我们使用BrowserStack的强大开源协作,在平台上使用虚拟机在真实浏览器中测试Mockjax。我们在下面主要浏览器的当前版本以及指定的Internet Explorer的特定版本上运行所有测试。

      • Edge
      • Firefox
      • Chrome
      • Safari
      • Internet Explorer 9-11

      在将代码合并到master之前,每个PR将使用TravisCI运行这些测试以进行持续集成,以确保我们不会引入回归。

      以其他方式使用Mockjax

      您可以将Mockjax用作Node模块,使用require.js,或使用Browserify ……并且可能还有其他方式。我们对上述每种方法都进行了测试。

      当使用Mockjax作为Node模块(包括Browserify)时,必须为模块提供jQuery库和awindow。以下是使用模块作为“浏览器化”模块的示例:

      var jquery =  require(' jquery ');
      var mockjax =  require(' jquery-mockjax ')(jquery,window);
      //请注意,我们希望
      在浏览器中对此文件进行浏览并//使用后,才能定义`window` 。如果不是Mockjax会有问题!
      
      var jquery = require('jquery');
      var mockjax = require('jquery-mockjax')(jquery, window);
      // Note that we expect `window` to be defined once this file is browserified and
      // used in a browser. If it isn't Mockjax will have a problem!
      
      mockjax({
          url: '/resource',
          responseText: 'content'
      });
      
      function getResource(cb) {
          jquery.ajax({
              url: '/resource',
              success: cb,
              error: cb
          });
      }
      

      记录

      Mockjax将各种信息记录到浏览器中的console(on window)或Node中的stdout中。您可以自定义日志记录的各个方面以满足您的需求。默认情况下,仅显示“错误”,“警告”或“信息”消息,但调试日志中可能会提供详细信息。以下是您可能需要做的一些常见事情,以获得更好的日志记录信息。

      显示不同级别的日志消息

      $.mockjaxSettings.logging = 4;  // very verbose debug messages
      $.mockjaxSettings.logging = 3;  // verbose log messages
      $.mockjaxSettings.logging = 2;  // informational messages
      $.mockjaxSettings.logging = 1;  // warning messages
      $.mockjaxSettings.logging = 0;  // only critical error messages
      

      (请注意,每个级别启用该级别加上任何较低的数字…因此设置日志记录2也会启用警告和错误。)

      实现自定义记录器

      如果您不想使用该console对象,则可以使用该logger设置传入您自己的日志记录实现。请注意,您必须记录器或者实现debug,log,info,warn,和error方法,或者你也必须提供什么样的方式映射到5级(0〜4)。

      $.mockjaxSettings.logger = {
        debug: function() { ... },
        log: function() { ... },
        // ...
      };
      

      您的记录器方法可以接收任何数量的注销参数,可以是字符串或对象,类似于window.console对象方法的工作方式。

      如果您有一个使用不同方法名称的记录器,请在此数组中指定它们:

      $.mockjaxSettings.logLevelMethods = ['critical', 'bad', 'stuff', 'log', 'verbose'];
      

      请注意,此数组(索引0)中的第一个条目将是错误,而最后一个条目将是详细输出。超出索引的任何内容4都将被忽略。

      那个古老的log环境怎么样?

      这是一个未记录的功能,您可以log使用$.mockjaxSettings它来提供方法 ,但不再在内部使用。这个未记录的选项现在已被弃用,虽然它可以工作,但是所有级别的日志消息都将被发送给它。

      如果你不知道我们在谈论什么……好!别担心。实现自己的记录器的正确方法是通过 $.mockjaxSettings.logger

      目录
      目录