[docs] Describe request hooks by VasilyStrelyaev · Pull Request #2309 · DevExpress/testcafe

VasilyStrelyaev · 2018-04-11T15:53:10Z

\cc @DevExpress/testcafe-docs

VasilyStrelyaev · 2018-04-11T15:53:56Z

Not quite polished. just the first try, please review

VasilyStrelyaev · 2018-04-11T15:59:22Z

oh, and I forgot @miherlosev

testcafe-build-bot · 2018-04-11T16:02:22Z

✅ Tests for the commit 0f5b3ad have passed. See details.

helen-dikareva · 2018-04-12T12:54:39Z

+test
+    .requestHooks(logger)
+    ('test', async t => {
+        const r = logger.requests[0];


Meaningful name for this const is const request = logger.requests[0];. But in this case you have to write ugly code
console.log(request.request.url); . Thus, an array of requests contains no request but logs, otherwise e.g. id would be in request.request.id. Don't you think so? @VasilyStrelyaev @churkin @AlexanderMoskovkin Could we find more suitable name?

I've changed the variable name to logRecord

You can use all power of es6 and write

const { request } = logger.requests[0];

logRecord is ok for me too.

helen-dikareva · 2018-04-12T12:55:30Z

+Property | Type | Description
+-------- | ---- | -----------
+`id`         | String | The ID of the request (generated by the logger).
+`testRunId`  | String | The ID of the test run that sent the request. Use it to identify the test in which the request originated.


I think we should give an example of using testRunId

I doubt we should expose testRunId. Do you know any cases when a user need it? /cc @miherlosev @VasilyStrelyaev

@miherlosev once said that grouping requests by the origin test is a use case

What's the real world case?

await t .expect(logRecord.id).eql('UnqLnm189') .expect(logRecord.testRunId).eql('IwQA12J12')

It does not make any sense. It will be always failed

ehm, I used to have console.log here instead of assertions, I guess I will go back to them.

I used to have console.log here instead of assertions

At first please describe why someone need it.

Don't need describe

AlexanderMoskovkin · 2018-04-12T13:04:26Z

+------ | ---- | ------------- | ---------
+`logRequestHeaders` | Boolean | Specifies whether the request headers should be logged. | `false`
+`logRequestBody` | Boolean | Specifies whether the request body should be logged. | `false`
+`stringifyRequestBody` | Boolean | Specifies whether the request body should be stored as a string or an object. | `false`


or an object

which kind of object?

I thought the body is just some custom object and that we don't know anything about it (i.e. can't give more details).
So you are saying that we can give more info here?

it should be Buffer

AlexanderMoskovkin · 2018-04-12T13:26:45Z

+Property | Type | Description
+-------- | ---- | -----------
+`id`         | String | The ID of the request (generated by the logger).
+`testRunId`  | String | The ID of the test run that sent the request. Use it to identify the test in which the request originated.


What's the real world case?

await t .expect(logRecord.id).eql('UnqLnm189') .expect(logRecord.testRunId).eql('IwQA12J12')

It does not make any sense. It will be always failed

testcafe-build-bot · 2018-04-12T13:28:19Z

✅ Tests for the commit d47a22c have passed. See details.

testcafe-build-bot · 2018-04-12T14:18:08Z

✅ Tests for the commit 1c4c8dd have passed. See details.

testcafe-build-bot · 2018-04-12T16:22:58Z

✅ Tests for the commit dc72750 have passed. See details.

kirovboris

/r-
I think we need to add some simple example(s) to take a look at the feature before the digging into details.

kirovboris · 2018-04-13T06:39:31Z

+* All TestCafe request hooks descend from the `RequestHook` class.
+
+    ```js
+    class MyRequestHook extends RequestHook {


Add import statement for RequestHook.

kirovboris · 2018-04-13T06:41:11Z

+* To determine which requests the hook handles, the base class constructor receives an array of [filtering rules](#specifying-which-requests-are-handled-by-the-hook) as the first parameter. If no rules are passed, all requests are handled.
+
+    ```js
+    export default class RequestHook {


export default is an extra noise for this example, just class RequestHook... Also you forgot to close }

kirovboris · 2018-04-13T06:45:35Z

+        constructor (requestFilterRules, responseEventConfigureOpts) {
+            console.log(responseEventConfigureOpts.includeHeaders); // false
+            console.log(responseEventConfigureOpts.includeBody);    // false
+        }


it should close }

kirovboris · 2018-04-13T06:51:05Z

+* To determine which requests the hook handles, the base class constructor receives an array of [filtering rules](#specifying-which-requests-are-handled-by-the-hook) as the first parameter. If no rules are passed, all requests are handled.
+
+    ```js
+    export default class RequestHook {


We need to describe class interface before detail explanation.

class RequestHook { constructor (requestFilterRules, responseEventConfigureOpts) { ... } onRequest (event) { ... } onResponse (event) { ... } }

kirovboris · 2018-04-13T06:53:57Z

+
+Property | Type | Description
+-------- | ---- | ------------
+`headers`     | Object  | The request headers in the property-value form.


These option tables contain a lot of stuff, let's add new item to the table of contents. It should be done for other huge option tables as well.

kirovboris · 2018-04-13T06:56:20Z

+`port`     | Number | The destination port.
+`path`     | String | The destination path.
+`method`   | String | The request method.
+`credentials` | Object | Credentials that were used to authenticate in the current session using NTLM or Basic authentication. For HTTP Basic authentication, these are `username` and `password`. NTLM authentication additionally specifies `workstation` and `domain`.


It would be great to describe credentials option in detail or to add a link if it's possible.

miherlosev · 2018-04-13T08:01:44Z

+* The request's HTTP method.
+* The status code received in the response.
+* The user agent that sent the request.
+* The ID of the test run that sent the request.


It needs only for customers which will create an own hook. I think we should not describe it.

miherlosev · 2018-04-13T08:02:38Z

+
+Property | Type | Description
+-------- | ---- | -----------
+`id`         | String | The ID of the request (generated by the logger).


Don't need describe.

miherlosev · 2018-04-13T08:03:03Z

+Property | Type | Description
+-------- | ---- | -----------
+`id`         | String | The ID of the request (generated by the logger).
+`testRunId`  | String | The ID of the test run that sent the request. Use it to identify the test in which the request originated.


Don't need describe

miherlosev · 2018-04-13T08:06:15Z

+### respond
+
+```text
+respond(body [, statusCode] [, headers])


body is an optional parameter too.

.onRequestTo(...).respond() returns an empty html page.

miherlosev · 2018-04-13T08:12:27Z

+
+Property | Type | Description
+-------- | ---- | --------------
+`requestId` | String | TestCafe internal request ID.


Don't describe

miherlosev · 2018-04-13T08:12:37Z

+`isAjax`    | Boolean | Specifies whether this is an AJAX request.
+`headers`   | Object | The request headers in the property-value form.
+`body`      | String | A stringified request body.
+`testRunId` | String | TestCafe internal ID of the test run that sent the request.


Dont' describe

miherlosev · 2018-04-13T08:13:57Z

+
+### Understanding How TestCafe Request Hooks Operate
+
+* All TestCafe request hooks descend from the `RequestHook` class.


descend -> inherit

miherlosev · 2018-05-03T12:05:56Z

+    .onRequestTo(/*...*/)
+    .respond('<html></html>') // an HTML response
+    .onRequestTo(/*...*/)
+    .respond(null, 204) // an empty response with a status code


One more case - respond with binary data

.onRequestTo(/*...*/) .respond(Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]))

testcafe-build-bot · 2018-05-04T14:22:01Z

❌ Tests for the commit 0118cd1 have failed. See details.

testcafe-build-bot · 2018-05-04T14:45:57Z

❌ Tests for the commit bb73c9b have failed. See details.

testcafe-build-bot · 2018-05-04T15:09:05Z

✅ Tests for the commit 1458509 have passed. See details.

MargaritaLoseva · 2018-05-08T10:08:51Z

@dirk-pieterse @miherlosev please review

miherlosev · 2018-05-08T10:12:43Z

    * [Assertion API](articles/documentation/test-api/assertions/assertion-api.md)
  * [Obtaining Data from the Client](articles/documentation/test-api/obtaining-data-from-the-client/README.md)
    * [Examples of Using Client Functions](articles/documentation/test-api/obtaining-data-from-the-client/examples-of-using-client-functions.md)
+  * [Intercepting and Mocking HTTP Requests](articles/documentation/test-api/intercepting-and-mocking-http-requests/README.md)


Intercepting and Mocking HTTP Requests -> Intercepting HTTP Requests
Mocking is a intercepting too.

miherlosev · 2018-05-08T10:52:40Z

+
+If you need to handle HTTP requests in a custom way, you can create your own request hook.
+
+The example below shows a custom hook that adds the `Authorization` header for JWT bearer authorization.


Convert to link - JWT

miherlosev · 2018-05-08T10:54:44Z

+
+Parameter | Type | Description
+--------- | ---- | ------------
+`hook`    | RequestHook | A request logger, mock or custom hook.


Should be RequestHook subclass. The build-in: RequestLogger or RequestMock or custom RequestHook written by customer.

So, I propose to change the line as:
hook | RequestHook subclass | A RequestLogger, RequestMock or custom user-defined hook.

miherlosev · 2018-05-08T11:05:04Z

+--------- | ---- | ------------
+`hook`    | RequestHook | A request logger, mock or custom hook.
+
+The `requestHooks` methods use the rest operator, which allows you to pass multiple hooks as parameters or arrays of hooks.


This sentence presents twice.
I think we should rewrite as:

The 'hook' parameter of fixture.requestHooks, test.requestHooks, t.addRequestHooks and t.removeRequestHooks is the rest operator.
It allows to pass multiple hooks or arrays of hooks as parameter.

Example

fixture.requestHooks(logger1, logger2, logger3, mock); test.requestHooks([logger1, logger2, logger3, mock])

miherlosev · 2018-05-08T11:09:33Z

+
+The request logger, mock and custom request hooks require that you specify which requests should be handled by them and which should be skipped.
+
+You can perform this filtering by passing the *request filtering rules* to the hook. Note that you can pass a single rule or an array of those.


You can setup or You can specify

miherlosev · 2018-05-08T11:41:54Z

+    .respond(responseMock2);
+```
+
+To enable the hook to mock the requests, [attach it to a test or fixture](attaching-hooks-to-tests-and-fixtures.md).


To enable the hook to mock the requests - it's unnecessary phrase.
Simplify to 'Then attach it to a test or fixture.' Or something like that.

The common request hook working scheme: firstly - configure, secondary - attach to fixture or test.

miherlosev · 2018-05-08T11:44:04Z

+
+Parameter | Type | Description   | Default
+--------- | ---- | ------------- | -----
+`body`&#160;*(optional)* | Object &#124; String &#124; Function | A mocked response body. Pass an object for a JSON response, a string for an HTML response or a function to build a custom response. | An empty HTML page is returned with the response.


Add Buffer type for body too.

miherlosev · 2018-05-08T11:48:46Z

+--------- | ---- | ------------- | -----
+`body`&#160;*(optional)* | Object &#124; String &#124; Function | A mocked response body. Pass an object for a JSON response, a string for an HTML response or a function to build a custom response. | An empty HTML page is returned with the response.
+`statusCode`&#160;*(optional)* | Number | The response status code. | `200`
+`headers`&#160;*(optional)* | Object | Custom headers added to the response in the property-value form.| The `content-type` header is provided.


Extend this:
If content-type is specified then its value will be used.

If content-type header is not specified then it will be calculated according the body type.
If body is object then content-type will be application/json.
if body has another type then content-type will be text/html; charset=utf-8.

miherlosev · 2018-05-08T11:52:10Z

+
+Parameter | Type | Description
+--------- | ---- | ---------------
+`req`     | Object | A request to be mocked.


This is request options from https://github.com/DevExpress/testcafe/pull/2309/files#diff-10e0cabf319ff29f01739d995e6ad73aR121.
Maybe need to place in separate paragraph or page?

miherlosev · 2018-05-08T11:53:15Z

+
+Method | Description
+------ | ---------------
+`setBody(value)` | Sets the `value` as the response body.


value parameter should be String.

testcafe-build-bot · 2018-05-10T08:48:51Z

✅ Tests for the commit e89d007 have passed. See details.

testcafe-build-bot · 2018-05-10T13:58:55Z

❌ Tests for the commit 90e7823 have failed. See details.

testcafe-build-bot · 2018-05-10T14:02:50Z

❌ Tests for the commit 90e7823 have failed. See details.

testcafe-build-bot · 2018-05-11T09:36:45Z

❌ Tests for the commit b40ff58 have failed. See details.

testcafe-build-bot · 2018-05-11T09:43:12Z

❌ Tests for the commit b40ff58 have failed. See details.

testcafe-build-bot · 2018-05-11T09:52:19Z

❌ Tests for the commit 4fb0c47 have failed. See details.

miherlosev · 2018-05-11T10:06:59Z

+
+Parameters | Type | Description | Default
+---------- | ---- | ----------- | -----
+`filter`&#160;*(optional)* | String &#124; RegExp &#124; Object &#124; Predicate | Specifies which requests should be mocked with a response that follows in the `respond` method. See [Specifying Which Requests are Handled by the Hook](specifying-which-requests-are-handled-by-the-hook.md). | All requests are mocked.


filter is required parameter

miherlosev · 2018-05-11T10:07:59Z

+
+Parameter | Type | Description   | Default
+--------- | ---- | ------------- | -----
+`body`&#160;*(optional)* | Object &#124; String &#124; Function &#124; Buffer | A mocked response body. Pass an object for a JSON response, a string for an HTML response or a function to build a custom response. | An empty HTML page is returned with the response.


Add link to the Buffer type

testcafe-build-bot · 2018-05-11T10:15:24Z

❌ Tests for the commit bf3f3f7 have failed. See details.

testcafe-build-bot · 2018-05-11T11:28:12Z

❌ Tests for the commit 6efaa50 have failed. See details.

testcafe-build-bot · 2018-05-11T12:27:50Z

❌ Tests for the commit 2c80769 have failed. See details.

testcafe-build-bot · 2018-05-11T12:52:05Z

✅ Tests for the commit cabbda8 have passed. See details.

MargaritaLoseva · 2018-05-11T13:42:00Z

@kirovboris @miherlosev fpr

miherlosev · 2018-05-11T13:51:37Z

    * [Assertion API](articles/documentation/test-api/assertions/assertion-api.md)
  * [Obtaining Data from the Client](articles/documentation/test-api/obtaining-data-from-the-client/README.md)
    * [Examples of Using Client Functions](articles/documentation/test-api/obtaining-data-from-the-client/examples-of-using-client-functions.md)
+  * [Intercepting HTTP Requests](articles/documentation/test-api/intercepting-and-mocking-http-requests/README.md)


Rename the filename too
articles/documentation/test-api/intercepting-http-requests/README.md

It isn't convenient to perform this from Vasily's fork.
I'll rename this topic and fix links to it from my fork in a separate PR after merging this PR.

* Describe request hooks * Address Helen's remarks * Revert an example * Specify the body type - Buffer * Change structure and address remarks * Add real-life examples * Update TOC * Fix broken links * Update README.md * Update README.md * Update README.md * Update attaching-hooks-to-tests-and-fixtures.md * Update creating-a-custom-http-request-hook.md * Update logging-http-requests.md * Update mocking-http-responses.md * Update specifying-which-requests-are-handled-by-the-hook.md * fix Mikhail's remark * fix Mikhail's remarks * attaching hooks - fix Mikhail's remarks * specifying-which-requests-are-handled -Fix remarks * creating-a-custom-http-request-hook - Fix remarks * logging-http-requests -- fix Mikhail's remark * remove Mocking from header * Remove Mocking from header * creating-a-custom-http-request-hook Fix remarks * mocking-http-responses Fix Mikhail's remarks * formatting added * remove trailing-spaces * Remove trailing spaces * mocking-http-responses.md Fix Mikhail's remarks * Remove trailing spaces * return previous permalink for Readme.md * return previous permalink for request hooks main topic * fix broken link

Describe request hooks

0f5b3ad

helen-dikareva reviewed Apr 12, 2018

View reviewed changes

Address Helen's remarks

d47a22c

AlexanderMoskovkin suggested changes Apr 12, 2018

View reviewed changes

Revert an example

1c4c8dd

Specify the body type - Buffer

dc72750

kirovboris suggested changes Apr 13, 2018

View reviewed changes

miherlosev requested changes Apr 13, 2018

View reviewed changes

Change structure and address remarks

accf85d

miherlosev requested changes May 3, 2018

View reviewed changes

Add real-life examples

0118cd1

Update TOC

bb73c9b

miherlosev mentioned this pull request May 4, 2018

Implement request hooks #1341

Closed

Fix broken links

1458509

miherlosev mentioned this pull request May 7, 2018

0.20.0 changelog miherlosev/tmp#5

Closed

AndreyBelym added this to the Sprint #11 milestone May 8, 2018

miherlosev requested changes May 8, 2018

View reviewed changes

Update README.md

e89d007

Update README.md

2f84503

logging-http-requests -- fix Mikhail's remark

90e7823

MargaritaLoseva added 4 commits May 11, 2018 12:23

remove Mocking from header

a157230

Remove Mocking from header

82f1fee

creating-a-custom-http-request-hook Fix remarks

4d023dd

mocking-http-responses Fix Mikhail's remarks

b40ff58

formatting added

4fb0c47

MargaritaLoseva added 2 commits May 11, 2018 13:05

remove trailing-spaces

a52a9b2

Remove trailing spaces

bf3f3f7

miherlosev requested changes May 11, 2018

View reviewed changes

MargaritaLoseva added 2 commits May 11, 2018 14:12

mocking-http-responses.md Fix Mikhail's remarks

b667a44

Remove trailing spaces

6efaa50

MargaritaLoseva added 2 commits May 11, 2018 15:14

return previous permalink for Readme.md

56e10f7

return previous permalink for request hooks main topic

2c80769

fix broken link

cabbda8

miherlosev requested changes May 11, 2018

View reviewed changes

miherlosev approved these changes May 11, 2018

View reviewed changes

kirovboris approved these changes May 14, 2018

View reviewed changes

MargaritaLoseva merged commit ac06c5d into DevExpress:master May 14, 2018

VasilyStrelyaev deleted the request-hooks branch May 17, 2018 14:40


		### Understanding How TestCafe Request Hooks Operate

		* All TestCafe request hooks descend from the `RequestHook` class.


		If you need to handle HTTP requests in a custom way, you can create your own request hook.

		The example below shows a custom hook that adds the `Authorization` header for JWT bearer authorization.


		The request logger, mock and custom request hooks require that you specify which requests should be handled by them and which should be skipped.

		You can perform this filtering by passing the request filtering rules to the hook. Note that you can pass a single rule or an array of those.

Conversation

VasilyStrelyaev commented Apr 11, 2018

Uh oh!

VasilyStrelyaev commented Apr 11, 2018

Uh oh!

VasilyStrelyaev commented Apr 11, 2018

Uh oh!

testcafe-build-bot commented Apr 11, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

testcafe-build-bot commented Apr 12, 2018

Uh oh!

testcafe-build-bot commented Apr 12, 2018

Uh oh!

testcafe-build-bot commented Apr 12, 2018

Uh oh!

kirovboris left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

testcafe-build-bot commented May 4, 2018

Uh oh!

testcafe-build-bot commented May 4, 2018

Uh oh!

testcafe-build-bot commented May 4, 2018

Uh oh!