You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Keploy](https://keploy.io) is a no-code testing platform that generates tests from API calls. This is the Typescript client SDK for recording and replaying the API Calls. There are 2 modes:
7
-
1.**Record mode**
8
-
1. Record requests, response and sends to Keploy server.
9
-
2. After keploy server removes duplicates, it then runs the request on the API again to identify noisy fields.
10
-
3. Sends the noisy fields to the keploy server to be saved along with the testcase.
11
-
2.**Test mode**
12
-
1. Fetches testcases for the app from keploy server.
13
-
2. Calls the API with same request payload in testcase.
14
-
3. Validates the respones and uploads results to the keploy server.
6
+
This is the client SDK for the [Keploy](https://github.com/keploy/keploy) testing platform. You can use this to generate realistic mock files or entire e2e tests for your applications. The **HTTP mocks/stubs and tests are the same format** and inter-exchangeable.
console.log(`Example app listening on port 3000!`));
45
-
module.exports= server;
46
-
```
47
-
48
-
## Configure
49
-
```
50
-
export KEPLOY_MODE="test"
51
-
export KEPLOY_APP_NAME="my-app"
52
-
export KEPLOY_APP_HOST="localhost"
53
-
export KEPLOY_APP_PORT=5050 # port on which server is running
54
-
export KEPLOY_APP_DELAY=5 # time delay before starting testruns(in seconds)
55
-
export KEPLOY_APP_TIMEOUT=100 # should be number
56
-
# export KEPLOY_APP_FILTER={"urlRegex":"*"} # should be json not to capture for certain url's
57
-
58
-
export KEPLOY_SERVER_URL="localhost:6789" # url to self hosted keploy grpc server
59
-
# export KEPLOY_SERVER_LICENSE="XXX-XXX-XXX" # hosted keploy server api key
60
-
```
61
-
### KEPLOY_MODE
62
-
There are 3 modes:
63
-
-**Record**: Sets to record mode.
64
-
-**Test**: Sets to test mode.
65
-
-**Off**: Turns off all the functionality provided by the API
66
-
67
-
**Note:**`KEPLOY_MODE` value is case sensitive.
68
-
69
-
## Generate E2E tests (with mocks)
70
23
71
-
```
72
-
export KEPLOY_TEST_CASE_PATH="./example" # If KEPLOY_TEST_CASE_PATH is not provided then a folder named keploy-tests will be made containing mocks folder. If KEPLOY_MOCK_PATH is provided then the mocks will be generated there.
**Note:** To enable `Test Export`, add `export ENABLE_TEST_EXPORT=true` in your .env file of [keploy-server](https://github.com/keploy/keploy) repository. If enabled, yaml files containing test cases will be generated in the directory provided by the user. Similarly, mocks will be generated in the yaml files.
28
+
2. Install and Start the keploy binary on an independent terminal. Follow [this](https://github.com/keploy/keploy#quick-installation) guide
29
+
## Usage
30
+
### Generate E2E tests
31
+
Keploy can generate end-to-end tests without writing any unit tests file and mocks.
32
+
Mocks/stubs are also generated and linked to their respective tests.
33
+
These tests can be run just by starting your API server on `test` mode.
34
+
We can also add code coverage using the recorded tests. Steps for integration:
35
+
1.**Integration**
36
+
1.`Add keploy middleware` to your API server. Follow the [Supported Routers](#supported-routers) guide for your router framework.
37
+
2.`Wrap the dependencies` of your API server like mongoose, etc. Follow the [Supported Dependencies](#supported-dependencies) guide for your dependencies.
38
+
3.`Configuration`: SDK uses environment variables for configuration. "KEPLOY_APP_PORT" is mandatory during, "record"/"test" modes. Other environment variables are optional, since they have default values.
39
+
40
+
Following is an example of `.env` file configuration.
41
+
```bash
42
+
export KEPLOY_APP_PORT=XXXX # port on which API is running. Required and it should be a number
export KEPLOY_APP_NAME="my-app"# [app_ids] for different API applications. Default: "sample-app"
45
+
export KEPLOY_APP_HOST="localhost"# Host of API application. Default: "localhost"
46
+
export KEPLOY_APP_DELAY=5 # approx time taken by API server to start. Default: 5sec
47
+
export KEPLOY_APP_TIMEOUT=100 # request timeout for keploy server. Default: 60sec
48
+
# export KEPLOY_APP_FILTER={"urlRegex":"*"} # filters for capturing tcs. It should be a valid JSON
49
+
50
+
export KEPLOY_SERVER_URL="localhost:6789"# url to running keploy server. Default: "localhost:6789"
51
+
# export KEPLOY_SERVER_LICENSE="XXX-XXX-XXX" # hosted keploy server api key
52
+
```
53
+
2. **Record**
54
+
1. Set the `KEPLOY_MODE` to "record"in your .env configuration file.
55
+
```bash
56
+
export KEPLOY_MODE="record"
57
+
```
58
+
2. Start your API server on `record` mode.
59
+
```bash
60
+
# <server>.js should be the main file to start API server.
61
+
source .env && node <server>.js
62
+
```
63
+
3. `Make an API call` on any endpoint of your running API server.
64
+
65
+
Now, testcases will be generated forthe API call along with the integrated dependencies mocks/stubs. These tests and mocks are generated as `readable/editable` yaml filesin the */keploy* directory.
66
+
3. **Test**
67
+
1. Set the `KEPLOY_MODE` to "test"in your .env configuration file.
68
+
```bash
69
+
export KEPLOY_MODE="test"
70
+
```
71
+
2. Start your API server on `test` mode.
72
+
```bash
73
+
# <server>.js should be the main file to start API server.
74
+
source .env && node <server>.js
75
+
```
76
+
77
+
🎉TADA: You have made an end-to-end test and tested it without writing any code fortest file or managing mocks/stubs.
78
+
79
+
Keploy can be integrated with testing frameworks like Mocha.js for`code coverage`.
80
+
Integartion with fameworks is provided in [Test with code coverage](#test-with-code-coverage) section.
81
+
### Mocking/Stubbing for unit tests
82
+
These mocks/stubs are realistic and frees you up from writing them manually. Keploy creates `readable/editable` mocks/stubs yaml files which can be referenced in any of your unit-tests tests. Steps to mock/stub external calls:
83
+
84
+
1. **Wrap the dependencies**:
85
+
1. `Initialise keploy context` by calling mock.NewContext intest setup for each testcase.
2. `Wrap the dependencies` of your unit tests like mongoose, etc. Follow the [Supported Dependencies](#supported-dependencies) guide for your dependencies.
92
+
2. **Record**:
93
+
1. Set the mode to `record`in NewContext.
94
+
```js
95
+
// input a unique test name foreach testcasein the Name field
96
+
NewContext({Mode: "record", Name: "unit_test-1"})
97
+
```
98
+
2. Run your unit test.
99
+
100
+
Now, a */mocks* directory is created containing yaml file for each testcase of your unit test.
101
+
The yaml files contains the recorded `outputs` of external depedencies as yaml docs.
102
+
3. **Test**:
103
+
1. Set the mode to `test`in your test setup.
104
+
```js
105
+
// input a unique test name foreach testcasein the Name field
106
+
NewContext({Mode: "test", Name: "unit_test-1"})
107
+
```
108
+
2. Turn off the dependency service like mongoDB server, etc.
109
+
3. Run the unit test.
110
+
111
+
🎉TADA: The unit test will run perfectly, without making any external dependency call.
112
+
It uses the recorded outputs from yaml files in generated mocks directory.
113
+
114
+
An example is provided in [Sample unit testfor Mocking/Stubing](#sample-unit-test-for-mockingstubing) section.
77
115
78
116
## Supported Routers
79
117
### 1. Express
118
+
Keploy adds a middleware for capturing requests/responses using require hooks. To integrate, just add the following statement before your require statement of `express`.
80
119
```js
120
+
// Uncomment following blocks to use require in ES Module
This statement should be at the top of your main file (server.js).
112
-
113
-
Note:- Import statements can't be used. Only CommonJs support is currently provided.
114
-
## Development Setup
115
-
116
-
- This project uses [Yarn](https://yarnpkg.com/) for package management. To install yarn, please make sure [Node](https://nodejs.org/en/) is installed and then:
117
-
118
-
```sh
119
-
npm i -g yarn
120
-
```
121
-
122
-
- To install local dependencies, assuming you are at root of the project:
123
163
124
-
```sh
125
-
yarn install
164
+
### 2. Mongoose
165
+
To integrate, just add this line before require statement of mongoose in your application.
166
+
```js
167
+
// Uncomment following blocks to use require in ES Module
Mongoose package version should be `^6.4.0`. Keploy mocks/stubs outputs for following mongoose methods:
178
+
1. find()
179
+
2. findOne()
180
+
3. save()
181
+
4. create()
182
+
5. insertMany()
183
+
6. updateOne()
184
+
7. updateMany()
185
+
8. deleteOne()
186
+
9. deleteMany()
127
187
128
-
### How to use mock library
188
+
## Sample unit test for Mocking/Stubing
129
189
130
-
The external calls from unit tests will be recorded and replayed as mocks from yaml files under a directory named mocks.
131
-
132
-
Following is an example of unit test with octokit :
190
+
Following is an example of `CommonJS` module unit test with octokit dependency :
133
191
134
192
#### Example
135
193
```js
@@ -168,7 +226,6 @@ describe('routes', function () {
168
226
});
169
227
});
170
228
```
171
-
Above example test is written in commonjs module.
172
229
173
230
**Note**: Since, this package uses require-in-the-middle for adding hook. Therefore, it is supported for commonjs module currently. Also, you can use require statements in esmodule by:
174
231
```js
@@ -177,8 +234,11 @@ import { createRequire } from "module";
177
234
const require = createRequire(import.meta.url);
178
235
```
179
236
180
-
### Integration with Mocha testing framework
181
-
You just need to do some imports and call a built-in assert function in your code in your unit test file and that's it!!🔥🔥🔥
237
+
## Test with code coverage
238
+
### Integration with Mocha testing framework
239
+
To see code coverage please use nyc mocha and see how many lines are covered!!
240
+
241
+
You just need to create a unit test file with the following code. And that's it!!🔥🔥🔥
182
242
```js
183
243
const {runServer} = require('../server') //your server wrapper
Note:- To see code coverage please use nyc mocha and see how many lines are covered!!
201
260
202
-
Note:- Jest is not supported currently!!
261
+
Note:- Since, Jest framework have an isolated environment. Keploy is unable to add hooks for integration.
203
262
263
+
## Development Setup
204
264
205
-
- Furthermore, to commit your changes use `yarn commit` instead of `git commit` for better commit experience.
265
+
- This project uses [Yarn](https://yarnpkg.com/) for package management. To install yarn, please make sure [Node](https://nodejs.org/en/) is installed and then:
266
+
267
+
```sh
268
+
npm i -g yarn
269
+
```
270
+
271
+
- To install local dependencies, assuming you are at root of the project:
206
272
273
+
```sh
274
+
yarn install
275
+
```
276
+
277
+
- To generate the js grpc files from services.proto:
0 commit comments