storj.io/minio@v0.0.0-20230509071714-0cbc90f649b1/mint/README.md (about)

     1  # Mint [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/mint.svg?maxAge=604800)](https://hub.docker.com/r/minio/mint/)
     2  
     3  Mint is a testing framework for Minio object server, available as a docker image. It runs correctness, benchmarking and stress tests. Following are the SDKs/tools used in correctness tests.
     4  
     5  - awscli
     6  - aws-sdk-go
     7  - aws-sdk-php
     8  - aws-sdk-ruby
     9  - aws-sdk-java
    10  - mc
    11  - minio-go
    12  - minio-java
    13  - minio-js
    14  - minio-py
    15  - minio-dotnet
    16  - s3cmd
    17  
    18  ## Running Mint
    19  
    20  Mint is run by `docker run` command which requires Docker to be installed. For Docker installation follow the steps [here](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/).
    21  
    22  To run Mint with Minio Play server as test target,
    23  
    24  ```sh
    25  $ docker run -e SERVER_ENDPOINT=play.minio.io:9000 -e ACCESS_KEY=Q3AM3UQ867SPQQA43P2F \
    26               -e SECRET_KEY=zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG -e ENABLE_HTTPS=1 minio/mint
    27  ```
    28  
    29  After the tests are run, output is stored in `/mint/log` directory inside the container. To get these logs, use `docker cp` command. For example
    30  ```sh
    31  docker cp <container-id>:/mint/log /tmp/logs
    32  ```
    33  
    34  ### Mint environment variables
    35  
    36  Below environment variables are required to be passed to the docker container. Supported environment variables:
    37  
    38  | Environment variable | Description | Example |
    39  |:--- |:--- |:--- |
    40  | `SERVER_ENDPOINT` | Endpoint of Minio server in the format `HOST:PORT`; for virtual style `IP:PORT` | `play.minio.io:9000` |
    41  | `ACCESS_KEY` | Access key of access `SERVER_ENDPOINT` | `Q3AM3UQ867SPQQA43P2F` |
    42  | `SECRET_KEY` | Secret Key of access `SERVER_ENDPOINT` | `zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG` |
    43  | `ENABLE_HTTPS` | (Optional) Set `1` to indicate to use HTTPS to access `SERVER_ENDPOINT`. Defaults to `0` (HTTP) | `1` |
    44  | `MINT_MODE` | (Optional) Set mode indicating what category of tests to be run by values `core`, `full`. Defaults to `core` | `full` |
    45  | `DOMAIN` | (Optional) Value of MINIO_DOMAIN environment variable used in Minio server | `myminio.com` |
    46  | `ENABLE_VIRTUAL_STYLE` | (Optional) Set `1` to indicate virtual style access . Defaults to `0` (Path style) | `1` |
    47  | `RUN_ON_FAIL` | (Optional) Set `1` to indicate execute all tests independent of failures (currently implemented for minio-go and minio-java) . Defaults to `0` (Path style) | `1` |
    48  
    49  
    50  ### Test virtual style access against Minio server
    51  
    52  To test Minio server virtual style access with Mint, follow these steps:
    53  
    54  - Set a domain in your Minio server using environment variable MINIO_DOMAIN. For example `export MINIO_DOMAIN=myminio.com`.
    55  - Start Minio server.
    56  - Execute Mint against Minio server (with `MINIO_DOMAIN` set to `myminio.com`) using this command
    57  ```sh
    58  $ docker run -e "SERVER_ENDPOINT=192.168.86.133:9000" -e "DOMAIN=minio.com"  \
    59  	     -e "ACCESS_KEY=minio" -e "SECRET_KEY=minio123" -e "ENABLE_HTTPS=0" \
    60  	     -e "ENABLE_VIRTUAL_STYLE=1" minio/mint
    61  ```
    62  
    63  ### Mint log format
    64  
    65  All test logs are stored in `/mint/log/log.json` as multiple JSON document.  Below is the JSON format for every entry in the log file.
    66  
    67  | JSON field | Type | Description | Example |
    68  |:--- |:--- |:--- |:--- |
    69  | `name` | _string_ | Testing tool/SDK name | `"aws-sdk-php"` |
    70  | `function` | _string_ | Test function name | `"getBucketLocation ( array $params = [] )"` |
    71  | `args` | _object_ | (Optional) Key/Value map of arguments passed to test function | `{"Bucket":"aws-sdk-php-bucket-20341"}` |
    72  | `duration` | _int_ | Time taken in milliseconds to run the test | `384` |
    73  | `status` | _string_ | one of `PASS`, `FAIL` or `NA` | `"PASS"` |
    74  | `alert` | _string_ | (Optional) Alert message indicating test failure | `"I/O error on create file"` |
    75  | `message` | _string_ | (Optional) Any log message | `"validating checksum of downloaded object"` |
    76  | `error` | _string_ | Detailed error message including stack trace on status `FAIL` | `"Error executing \"CompleteMultipartUpload\" on ...` |
    77  
    78  ## For Developers
    79  
    80  ### Running Mint development code
    81  
    82  After making changes to Mint source code a local docker image can be built/run by
    83  
    84  ```sh
    85  $ docker build -t minio/mint . -f Dockerfile.mint
    86  $ docker run -e SERVER_ENDPOINT=play.minio.io:9000 -e ACCESS_KEY=Q3AM3UQ867SPQQA43P2F \
    87               -e SECRET_KEY=zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG \
    88               -e ENABLE_HTTPS=1 -e MINT_MODE=full minio/mint:latest
    89  ```
    90  
    91  
    92  ### Adding tests with new tool/SDK
    93  
    94  Below are the steps need to be followed
    95  
    96  - Create new app directory under [build](https://github.com/minio/mint/tree/master/build) and [run/core](https://github.com/minio/mint/tree/master/run/core) directories.
    97  - Create `install.sh` which does installation of required tool/SDK under app directory.
    98  - Any build and install time dependencies should be added to [install-packages.list](https://github.com/minio/mint/blob/master/install-packages.list).
    99  - Build time dependencies should be added to [remove-packages.list](https://github.com/minio/mint/blob/master/remove-packages.list) for removal to have clean Mint docker image.
   100  - Add `run.sh` in app directory under `run/core` which execute actual tests.
   101  
   102  #### Test data
   103  Tests may use pre-created data set to perform various object operations on Minio server.  Below data files are available under `/mint/data` directory.
   104  
   105  | File name |  Size |
   106  |:--- |:--- |
   107  | datafile-0-b | 0B |
   108  | datafile-1-b | 1B |
   109  | datafile-1-kB |1KiB |
   110  | datafile-10-kB |10KiB |
   111  | datafile-33-kB |33KiB |
   112  | datafile-100-kB |100KiB |
   113  | datafile-1-MB |1MiB |
   114  | datafile-1.03-MB |1.03MiB |
   115  | datafile-5-MB |5MiB |
   116  | datafile-6-MB |6MiB |
   117  | datafile-10-MB |10MiB |
   118  | datafile-11-MB |11MiB |
   119  | datafile-65-MB |65MiB |
   120  | datafile-129-MB |129MiB |