view release on metacpan or  search on metacpan

README-TESTING.md  view on Meta::CPAN

If you want to test *some* parts of this module but don't want to
spend a few pennies (or don't have access to AWS credentials) you can
try one of the S3 mocking services.  The two of the most popular services
seem to be:

* [LocalStack](https://localstack.io)
* [minio](https://min.io)

Both of these implement a subset of the S3 API. __Note that Some tests will fail
on both services (as of the writing of this document).__ To make it
through the tests, try setting one or more of the environment
variables above which will selectively skip some test.

If you are using a mocking service, you might find it useful to set
the environment variable AWS_EC2_METADATA_DISABLED to a true value.

```
export AWS_EC2_METADATA_DISABLED=true
```

This will prevent the AWS CLI from looking for metadata when you are
not actually running on an EC2 instance or container.  Without this
variable set, the CLI attempts to access the metadata service at
http://169.254.169.254/latest/meta-data/ until it eventually times out.

## Testing with LocalStack

LocalStack seems to be the easiest to work with and supports a number
of AWS APIs besides S3. It does not implement the full suite of APIs
however. In particular, LocalStack does not enforce ACLs. Accordingly,
those tests are skipped if the environment variable AMAZON_S3_LOCALSTACK
is set to any value.

A `docker-compose.yml` file is included now in the
project.

```
version: "3.8"

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME-localstack_main}"
    image: localstack/localstack
    hostname: s3
    networks:
      default:
        aliases:
          - s3.localhost.localstack.cloud
          - net-amazon-s3-test-test.localhost.localstack.cloud
    ports:
      - "127.0.0.1:4510-4530:4510-4530"
      - "127.0.0.1:4566:4566"
      - "127.0.0.1:4571:4571"
    environment:
      - SERVICES=s3,ssm,secretsmanager,kms,sqs,ec2,events,sts,logs
      - DEBUG=${DEBUG-}
      - DATA_DIR=${DATA_DIR-}
      - LAMBDA_EXECUTOR=${LAMBDA_EXECUTOR-}
      - HOST_TMP_FOLDER=${TMPDIR:-/tmp/}localstack
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:
      -  "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"
```

When testing with LocalStack you'll need to set some environment
variables to get through (the majority) of the tests.

Environment Variable | Value | Description
-------------------- | ----- | ----------- 
AMAZON_EXPENSIVE_TESTS | 1 | enables testing of S3 API
AMAZONS3_HOST | localhost:4566
AMAZON_S3_LOCALSTACK | any | skips some tests that will fail on LocalStack
AWS_ACCESS_KEY_ID | test | AWS access key for LocalStack
AWS_ACCESS_KEY_SECRET | test | AWS secret access key for LocalStack

In order to test domain name buckets, you will need to spoof a domain
name for your bucket by setting the name of the bucket in your
`/etc/hosts` file.

```
127.0.0.1 localhost net-amazon-s3-test-test.s3.localhost.localstack.cloud
```

To run tests using LocalStack...

```
 AMAZON_S3_EXPENSIVE_TESTS=1 \
 AMAZON_S3_HOST=s3.localhost.localstack.cloud:4566 \
 AMAZON_S3_LOCALSTACK=1 \
 AWS_ACCESS_KEY_ID=test \
 AWS_ACCESS_SECRET_KEY=test  \
 AMAZON_S3_DOMAIN_BUCKET_NAMES=1 make test
```