|
| 1 | +# mongosh Code Example Test PoC |
| 2 | + |
| 3 | +This is a PoC to explore testing mongosh code examples for MongoDB documentation. |
| 4 | + |
| 5 | +The structure of this JavaScript project is as follows: |
| 6 | + |
| 7 | +- `/examples`: This directory contains example code and output to validate. |
| 8 | +- `/tests`: This directory contains the test infrastructure to actually run |
| 9 | + the tests by invoking the example code. |
| 10 | + |
| 11 | +While running the tests, this test suite creates files in a `/temp` directory. We concatenate |
| 12 | +the code example with the necessary commands to connect to the deployment and use the correct |
| 13 | +database. |
| 14 | + |
| 15 | +## To run the tests locally |
| 16 | + |
| 17 | +### Create a MongoDB Docker Deployment |
| 18 | + |
| 19 | +To run these tests locally, you need a MongoDB Docker deployment. Make sure Docker is |
| 20 | +running, and then: |
| 21 | + |
| 22 | +1. Pull the MongoDB image from Docker Hub: |
| 23 | + |
| 24 | + ```shell |
| 25 | + docker pull mongo |
| 26 | + ``` |
| 27 | +2. Run the container: |
| 28 | + |
| 29 | + ```shell |
| 30 | + docker run --name mongodb-test -d -p 27017:27017 mongo |
| 31 | + ``` |
| 32 | + |
| 33 | +3. Verify the container is running: |
| 34 | + |
| 35 | + ```shell |
| 36 | + docker ps |
| 37 | + ``` |
| 38 | + |
| 39 | +The output resembles: |
| 40 | + |
| 41 | +```shell |
| 42 | +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
| 43 | +ef70cce38f26 mongo "/usr/local/bin/runn…" 29 hours ago Up 29 hours (healthy) 127.0.0.1:63201->27017/tcp mongodb-test |
| 44 | +``` |
| 45 | + |
| 46 | +You may note the actual port is different than `27017`, if something else is already running on |
| 47 | +`27017` on your machine. Note the port next to the IP address for running the tests. |
| 48 | + |
| 49 | +### Create a .env file |
| 50 | + |
| 51 | +Create a file named `.env` at the root of the `/mongosh` directory. |
| 52 | +Add the following values to your .env file, substituting the port where your local deployment |
| 53 | +is running: |
| 54 | + |
| 55 | +``` |
| 56 | +CONNECTION_STRING="mongodb://localhost:63201" |
| 57 | +CONNECTION_PORT="63201" |
| 58 | +``` |
| 59 | + |
| 60 | +### Install the dependencies |
| 61 | + |
| 62 | +This test suite requires you to have `Node.js` v20 or newer installed. If you |
| 63 | +do not yet have Node installed, refer to |
| 64 | +[the Node.js installation page](https://nodejs.org/en/download/package-manager) |
| 65 | +for details. |
| 66 | + |
| 67 | +From the root of the `/mongosh` directory, run the following command to install |
| 68 | +dependencies: |
| 69 | + |
| 70 | +``` |
| 71 | +npm install |
| 72 | +``` |
| 73 | + |
| 74 | +### Run the tests |
| 75 | + |
| 76 | +#### Run Tests from the IDE |
| 77 | + |
| 78 | +Normally, you could press the play button next to a test name to run a test |
| 79 | +in the IDE. Because this test suite relies on an Atlas connection string and |
| 80 | +environment value passed in from the environment, running tests in the IDE |
| 81 | +will fail unless you configure the IDE with the appropriate environment |
| 82 | +variables. |
| 83 | + |
| 84 | +In JetBrains IDEs, you can do the following: |
| 85 | + |
| 86 | +- Click the play button next to the test suite name |
| 87 | +- Select the `Modify Run Configuration` option |
| 88 | +- In the `Environment Variables` field, supply the appropriate environment variables |
| 89 | + - Note: you do not need to use quotes around the connection string in this field |
| 90 | + i.e. it should resemble: |
| 91 | + CONNECTION_STRING=mongodb://localhost:63201 |
| 92 | + |
| 93 | +#### Run All Tests from the command line |
| 94 | + |
| 95 | +From the `/mongosh` directory, run: |
| 96 | + |
| 97 | +``` |
| 98 | +npm test |
| 99 | +``` |
| 100 | + |
| 101 | +This invokes the following command from the `package.json` `test` key: |
| 102 | + |
| 103 | +``` |
| 104 | +jest --run-in-band --detectOpenHandles |
| 105 | +``` |
| 106 | + |
| 107 | +In the above command: |
| 108 | + |
| 109 | +- `jest` is the command to run the test suite |
| 110 | +- `--runInBand` is a flag that specifies only running one test at a time |
| 111 | + to avoid collisions when creating/editing/dropping indexes. Otherwise, Jest |
| 112 | + defaults to running tests in parallel. |
| 113 | +- `--detectOpenHandles` is a flag that tells Jest to track resource handles or async |
| 114 | + operations that remain open after the tests are complete. These can cause the test suite |
| 115 | + to hang, and this flag tells Jest to report info about these instances. |
| 116 | + |
| 117 | +#### Run Test Suites from the command line |
| 118 | + |
| 119 | +You can run all the tests in a given test suite (file). |
| 120 | + |
| 121 | +From the `/tests` directory, run: |
| 122 | + |
| 123 | +``` |
| 124 | +export $(xargs < ../.env) && jest -t '<text string from the 'describe' block you want to run>' --runInBand |
| 125 | +``` |
| 126 | + |
| 127 | +In the above command: |
| 128 | + |
| 129 | +- `export $(xargs < ../.env)` is Linux flag to make the contents of the `.env` |
| 130 | + file available to the test suite |
| 131 | +- `jest` is the command to run the test suite |
| 132 | +- `-t '<text string from the 'describe' block you want to run>'` is the way to |
| 133 | + specify to run all tests in test suite, which in this test, is a single file |
| 134 | +- `--runInBand` is a flag that specifies only running one test at a time |
| 135 | + to avoid collisions when creating/editing/dropping indexes. Otherwise, Jest |
| 136 | + defaults to running tests in parallel. |
| 137 | + |
| 138 | +#### Run Individual Tests from the command line |
| 139 | + |
| 140 | +You can run a single test within a given test suite (file). |
| 141 | + |
| 142 | +From the `/tests` directory, run: |
| 143 | + |
| 144 | +``` |
| 145 | +export $(xargs < ../.env) && jest -t '<text string from the 'it' block of the test you want to run>' |
| 146 | +``` |
| 147 | + |
| 148 | +In the above command: |
| 149 | + |
| 150 | +- `export $(xargs < ../.env)` is Linux flag to make the contents of the `.env` |
| 151 | + file available to the test suite |
| 152 | +- `jest` is the command to run the test suite |
| 153 | +- `-t '<text string from the 'it' block of the test you want to run>'` is the |
| 154 | + way to specify to run a single test matching your text |
| 155 | + |
| 156 | +Since you are only running a single test, there is no chance of colliding |
| 157 | +with the other tests, so the `--runInBand` flag isn't needed. |
0 commit comments