Newman: Update docs for `folder` option to include filtering individual request

[rohit-gohri]

1. Newman Version (can be found via newman -v): 4.5.7
2. OS details (type, version, and architecture): MacOS 10.13.4
3. Are you using Newman as a library, or via the CLI?: Library
4. Did you encounter this recently, or has this bug always been there: N/A
5. Expected behaviour:
   Newman's folder option is for filtering requests by folders/subfolders according to docs. But it can also be used to filter individual requests (just like it is possible in Runner). Either this is a bug or please update the docs to reflect the same.

1. Sample collection, and auxiliary files (minus the sensitive details):

Tests.postman_collection.json

{
    "info": {
        "_postman_id": "8749796c-f4b2-4bc7-bb0a-4ff75a4b5ad6",
        "name": "Tests",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "User",
            "item": [
                {
                    "name": "Create user",
                    "item": [
                        {
                            "name": "Create user",
                            "event": [
                                {
                                    "listen": "test",
                                    "script": {
                                        "id": "dc56e524-af80-47f2-bb6b-e60047966c18",
                                        "exec": [
                                            "pm.test('status ok', () => {",
                                            "    pm.response.to.have.statusCode(200);",
                                            "})"
                                        ],
                                        "type": "text/javascript"
                                    }
                                }
                            ],
                            "request": {
                                "method": "PUT",
                                "header": [
                                    {
                                        "key": "Content-Type",
                                        "name": "Content-Type",
                                        "value": "application/json",
                                        "type": "text"
                                    }
                                ],
                                "body": {
                                    "mode": "raw",
                                    "raw": "{{request_body}}",
                                    "options": {
                                        "raw": {
                                            "language": "json"
                                        }
                                    }
                                },
                                "url": {
                                    "raw": "localhost:3000/api/user/create",
                                    "host": [
                                        "localhost"
                                    ],
                                    "port": "3000",
                                    "path": [
                                        "api",
                                        "user",
                                        "create"
                                    ]
                                }
                            },
                            "response": []
                        }
                    ],
                    "protocolProfileBehavior": {},
                    "_postman_isSubFolder": true
                },
                {
                    "name": "Get user",
                    "item": [
                        {
                            "name": "Get user",
                            "event": [
                                {
                                    "listen": "test",
                                    "script": {
                                        "id": "ce9db536-6ad4-49a0-96fe-7a1423e4f6a4",
                                        "exec": [
                                            "pm.test('status ok', () => {",
                                            "    pm.response.to.have.statusCode(200);",
                                            "})"
                                        ],
                                        "type": "text/javascript"
                                    }
                                }
                            ],
                            "request": {
                                "method": "GET",
                                "header": [],
                                "url": {
                                    "raw": "localhost:3000/api/user/{{user_id}}",
                                    "host": [
                                        "localhost"
                                    ],
                                    "port": "3000",
                                    "path": [
                                        "api",
                                        "user",
                                        "{{user_id}}"
                                    ]
                                }
                            },
                            "response": []
                        }
                    ],
                    "protocolProfileBehavior": {},
                    "_postman_isSubFolder": true
                },
                {
                    "name": "Delete user",
                    "event": [
                        {
                            "listen": "test",
                            "script": {
                                "id": "7f0215b7-5087-4472-b994-29a42974b1e1",
                                "exec": [
                                    "pm.test('status ok', () => {",
                                    "    pm.response.to.have.statusCode(200);",
                                    "})"
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "DELETE",
                        "header": [],
                        "url": {
                            "raw": "localhost:3000/api/user/{{user_id}}",
                            "host": [
                                "localhost"
                            ],
                            "port": "3000",
                            "path": [
                                "api",
                                "user",
                                "{{user_id}}"
                            ]
                        }
                    },
                    "response": []
                },
                {
                    "name": "Update user",
                    "event": [
                        {
                            "listen": "prerequest",
                            "script": {
                                "id": "47b707b7-46e9-41ca-9e55-3f74861bdadb",
                                "exec": [
                                    ""
                                ],
                                "type": "text/javascript"
                            }
                        },
                        {
                            "listen": "test",
                            "script": {
                                "id": "27ce6b9d-9417-4520-9fe3-b36ef178c783",
                                "exec": [
                                    "pm.test('status ok', () => {",
                                    "    pm.response.to.have.statusCode(200);",
                                    "})"
                                ],
                                "type": "text/javascript"
                            }
                        }
                    ],
                    "request": {
                        "method": "POST",
                        "header": [
                            {
                                "key": "Content-Type",
                                "name": "Content-Type",
                                "value": "application/json",
                                "type": "text"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{{request_body}}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "url": {
                            "raw": "localhost:3000/api/user/{{user_id}}",
                            "host": [
                                "localhost"
                            ],
                            "port": "3000",
                            "path": [
                                "api",
                                "user",
                                "{{user_id}}"
                            ]
                        }
                    },
                    "response": []
                }
            ],
            "protocolProfileBehavior": {}
        }
    ],
    "protocolProfileBehavior": {}
}

1. Screenshots (if applicable):

As can be seen in the screenshot, filtering a single request is possible in the Collection Runner. The same is possible through the folder option but is not mentioned in the docs.

[rohit-gohri]

Related to https://github.com/postmanlabs/newman/issues/1990
This only works if the name is unique (until path support comes), if multiple requests with the same name exist then the outermost and then the first is run.

[Suhasnama]

Hi @rohit-gohri ,
As specified by you , i find no where in docs about filtering folders/sub-folders to run individual requests.
According to my knowledge it is not yet available for newman , though it is available in the Postman Runner.(Correct me if i am wrong!)

1. Expected behaviour:
   Newman's folder option is for filtering requests by folders/subfolders according to docs. But it can also be used to filter individual requests (just like it is possible in Runner). Either this is a bug or please update the docs to reflect the same.

[rohit-gohri]

According to my knowledge it is not yet available for newman , though it is available in the Postman Runner.(Correct me if i am wrong!)

That's what this issue is for, it works in newman also but is not mentioned in docs.
As mentioned here: https://github.com/postmanlabs/newman/issues/1851#issuecomment-452184189

[Suhasnama]

Never knew that --folder switch could do that, just verified it locally, I will update the docs and will open a PR by tonight.
Thanks for the explanation @rohit-gohri !!

[Suhasnama]

Opened a new PR for this issue #2253

[codenirvana]

Closing as the following PR https://github.com/postmanlabs/newman/pull/2253 got merged.