issue-183: Use tags instead of suites to separate tests

.github/workflows/build.yml

@@ -19,8 +19,6 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Commenting Windows out in order to preserve our free minutes.
-        # We can re-enable it, if we get a sponsor.
         os: [ubuntu-latest, windows-latest, macos-latest]
         java: [ 8, 11.0.3 ]
     env:
@@ -44,11 +42,21 @@ jobs:
         uses: actions/cache@v2
         with:
           path: ~/.m2/repository
-          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          # https://github.com/actions/cache/issues/2#issuecomment-673493515
+          # Example: unix timestamp
+          key: ${{ runner.os }}-maven-${{ secrets.MVN_CACHE_VERSION }}-${{ hashFiles('**/pom.xml') }}
           restore-keys: |
-            ${{ runner.os }}-maven-
+            ${{ runner.os }}-maven-${{ secrets.MVN_CACHE_VERSION }}-
+      - name: Maven Version
+        run: mvn --version
       - name: Build with Maven
-        run: mvn clean install -Pjacoco-code-coverage
+        run: mvn clean install -Pit-s3 -Pjacoco-code-coverage
+        env:
+          S3FS_BUCKET_NAME: ${{ secrets.S3FS_BUCKET_NAME }}
+          S3FS_ACCESS_KEY: ${{ secrets.S3FS_ACCESS_KEY }}
+          S3FS_SECRET_KEY: ${{ secrets.S3FS_SECRET_KEY }}
+          S3FS_REGION: ${{ secrets.S3FS_REGION }}
+          S3FS_PROTOCOL: "https"
       - name: Publish code analysis to Sonarcloud
         # [WARNING] The version of Java 1.8 you have used to run this analysis is deprecated and we will stop accepting
         #           it from October 2020. Please update to at least Java 11.
@@ -58,4 +66,4 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-        run: mvn org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Pjacoco-code-coverage -DskipTests
+        run: mvn org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -Pjacoco-code-coverage -DskipTests

docs/content/assets/resources/s3fs-nio-strict-policy.json

@@ -0,0 +1,29 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "VisualEditor0",
+      "Effect": "Allow",
+      "Action": [
+        "s3:PutObject",
+        "s3:GetObjectAcl",
+        "s3:GetObject",
+        "s3:DeleteObjectVersion",
+        "s3:PutReplicationConfiguration",
+        "s3:ListBucket",
+        "s3:DeleteObject",
+        "s3:GetBucketAcl"
+      ],
+      "Resource": [
+        "arn:aws:s3:::YOUR_BUCKET_NAME",
+        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
+      ]
+    },
+    {
+      "Sid": "VisualEditor1",
+      "Effect": "Allow",
+      "Action": "s3:ListAllMyBuckets",
+      "Resource": "*"
+    }
+  ]
+}

docs/content/contributing/developer-guide/index.md

@@ -21,6 +21,49 @@ contributors to help with are marked with the following labels:
 [![GitHub issues by-label help-wanted-link][help-wanted-badge]][help-wanted-link] 
 [![GitHub issues by-label hacktoberfest-link][hacktoberfest-badge]][hacktoberfest-link] 
 
+## Preparing credentials
+
+### S3 - Easy
+
+!!! warning "Gives access to **all** buckets which could be dangerous!"
+
+The easiest way to get started would be to:
+
+1. Go to the [Identity and Access Management (IAM)][s3-iam]
+2. Go to `Users` -> `Add User`:
+     * Username: `my-s3fs-username` (or whatever)
+     * Access Type: `Programmatic access` must be selected!
+3. `Set Permissions`:
+     * Select `Attach existing policies directly`
+     * Search for `AmazonS3FullAccess` and select it.
+4. Continue with next steps (apply changes if necessary)
+5. At the final step you will receive an `Access Key` and `Secret Access Key` - copy those into your 
+   `amazon-test.properties` or export them as `S3FS_**` env variable name (if running in a container).
+
+
+### S3 - Advanced
+
+!!! success "Allows access to a specific bucket and is safer if you have multiple buckets in your account."
+
+1. Go to the [Identity and Access Management (IAM)][s3-iam]
+2. Go to `Policies`:
+    * Create a new policy
+    * Switch to `JSON` editor and copy the policy below which will limit the access to only a specific bucket:
+      ```
+      --8<-- "./content/assets/resources/s3fs-nio-strict-policy.json"
+      ```
+    * Replace `YOUR_BUCKET_NAME` with your actual bucket name.
+    * Give a name and save (i.e. `s3fs-full-access-to-YOUR_BUCKET_NAME`)
+3. Go to `Users` -> `Add User`:
+    * Username: `my-s3fs-username` (or whatever)
+    * Access Type: `Programmatic access` must be selected!
+4. `Set Permissions`:
+    * Select `Attach existing policies directly`
+    * Search for `s3fs-full-access-to-YOUR_BUCKET_NAME` and select it
+    * Continue with next steps (apply changes if necessary)
+5. At the final step you will receive an `Access Key` and `Secret Access Key` - copy those into your
+   `amazon-test.properties` or export them as `S3FS_**` env variable name (if running in a container).
+
 ## Building the code
 
 
@@ -69,3 +112,6 @@ TODO: Add a guide to run tests with MinIO and docker-compose
 [help-wanted-badge]: https://img.shields.io/github/issues-raw/carlspring/s3fs-nio/help%20wanted.svg?label=help%20wanted&color=%23856bf9& 
 [hacktoberfest-link]: {{ repo_url }}/issues?q=is%3Aissue+is%3Aopen+label%3A%22hacktoberfest%22
 [hacktoberfest-badge]: https://img.shields.io/github/issues-raw/carlspring/s3fs-nio/hacktoberfest.svg?label=hacktoberfest&color=orange
+
+[<--# S3 -->]: #
+[s3-iam]: https://console.aws.amazon.com/iam/home

docs/content/index.md

@@ -33,7 +33,7 @@
 2. Open [IAM] and go to `Add User`
 3. Set `Access Type` to `Programmatic Access` or you will get `403 Forbidden` errors.
 4. Select `Attach an existing policies directly`
-5. Select `AmazonS3FullAccess` policy and `Create user`
+5. Select `AmazonS3FullAccess` policy and `Create user` (if you prefer more fine-grained access [click here](./contributing/developer-guide/index.md#s3-advanced))
 6. Copy `Access key ID` and `Secret access key` - you will need them later!
 
 ### Example

pom.xml

@@ -86,7 +86,6 @@
         <version.tika>1.25</version.tika>
         <version.findbugs.jsr305>3.0.2</version.findbugs.jsr305>
         <version.junit>5.7.0</version.junit>
-        <version.junit.platform.runner>1.7.0</version.junit.platform.runner>
         <version.mockito>3.7.7</version.mockito>
         <version.marschall.memoryfilesystem>2.1.0</version.marschall.memoryfilesystem>
     </properties>
@@ -108,9 +107,10 @@
                 <artifactId>maven-surefire-plugin</artifactId>
                 <version>3.0.0-M5</version>
                 <configuration>
-                    <excludes>
-                        <exclude>**/*ITTest*</exclude>
-                    </excludes>
+                    <!-- Make sure the build fails if no tests are executed! -->
+                    <failIfNoTests>true</failIfNoTests>
+                    <!-- Since we are not tagging unit tests, this actually means "execute all non-tagged tests" -->
+                    <excludedGroups>*</excludedGroups>
                 </configuration>
             </plugin>
             <plugin>
@@ -242,10 +242,11 @@
             <version>${version.junit}</version>
             <scope>test</scope>
         </dependency>
+
         <dependency>
-            <groupId>org.junit.platform</groupId>
-            <artifactId>junit-platform-runner</artifactId>
-            <version>${version.junit.platform.runner}</version>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-lang3</artifactId>
+            <version>3.11</version>
             <scope>test</scope>
         </dependency>
 
@@ -287,32 +288,89 @@
 
     <profiles>
         <profile>
-            <id>integration-tests</id>
+            <id>it-s3</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-failsafe-plugin</artifactId>
+                        <version>3.0.0-M5</version>
+                        <configuration>
+                            <!-- Make sure the build fails if no tests are executed! -->
+                            <failIfNoTests>true</failIfNoTests>
+                            <includes>
+                                <include>**/*IT.java</include>
+                            </includes>
+                            <systemPropertyVariables>
+                                <!-- used in EnvironmentBuilder.java -->
+                                <running.it>s3</running.it>
+                            </systemPropertyVariables>
+                        </configuration>
+                        <executions>
+                            <execution>
+                                <id>it-s3</id>
+                                <phase>integration-test</phase>
+                                <goals>
+                                    <goal>integration-test</goal>
+                                </goals>
+                                <!-- This configuration must happen at execution level, otherwise you'll get: -->
+                                <!-- Skipping execution of surefire because it has already been run for this configuration -->
+                                <configuration>
+                                    <!-- Include only s3 tagged integration tests -->
+                                    <groups>it-s3</groups>
+                                    <excludedGroups>*</excludedGroups>
+                                </configuration>
+                            </execution>
+                            <execution>
+                                <id>it-s3-verify</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>verify</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
 
+        <profile>
+            <!-- This should work but is not tested since it depends on https://github.com/carlspring/s3fs-nio/issues/60 -->
+            <id>it-minio</id>
             <build>
                 <plugins>
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-failsafe-plugin</artifactId>
                         <version>3.0.0-M5</version>
                         <configuration>
+                            <!-- Make sure the build fails if no tests are executed! -->
+                            <failIfNoTests>true</failIfNoTests>
                             <includes>
-                                <include>**/*ITSuite.java</include>
+                                <include>**/*IT.java</include>
                             </includes>
-                            <excludes>
-                                <exclude>**/**Test.java</exclude>
-                            </excludes>
+                            <systemPropertyVariables>
+                                <!-- used in EnvironmentBuilder.java -->
+                                <running.it>minio</running.it>
+                            </systemPropertyVariables>
                         </configuration>
                         <executions>
                             <execution>
-                                <id>integration-test</id>
+                                <id>it-minio</id>
                                 <phase>integration-test</phase>
                                 <goals>
                                     <goal>integration-test</goal>
                                 </goals>
+                                <!-- This configuration must happen at execution level, otherwise you'll get: -->
+                                <!-- Skipping execution of surefire because it has already been run for this configuration -->
+                                <configuration>
+                                    <!-- Include only s3 tagged integration tests -->
+                                    <groups>it-minio</groups>
+                                    <excludedGroups>*</excludedGroups>
+                                </configuration>
                             </execution>
                             <execution>
-                                <id>verify</id>
+                                <id>it-minio-verify</id>
                                 <phase>verify</phase>
                                 <goals>
                                     <goal>verify</goal>
@@ -323,6 +381,7 @@
                 </plugins>
             </build>
         </profile>
+
         <profile>
             <id>jacoco-code-coverage</id>
 

src/main/java/org/carlspring/cloud/storage/s3fs/S3FileStore.java

@@ -117,6 +117,12 @@ public Bucket getBucket()
         return getBucket(name);
     }
 
+    /**
+     * This code requires `s3:ListAllMyBuckets` permission.
+     *
+     * @param bucketName
+     * @return
+     */
     private Bucket getBucket(final String bucketName)
     {
         for (Bucket buck : getClient().listBuckets().buckets())

src/main/java/org/carlspring/cloud/storage/s3fs/S3Path.java

@@ -64,7 +64,7 @@ public class S3Path
      */
     public S3Path(S3FileSystem fileSystem, String first, String... more)
     {
-        Preconditions.checkArgument(first != null, "first path must be not null");
+        Preconditions.checkArgument(first != null, "first path must be not null, maybe you forgot to set the bucket name?");
         Preconditions.checkArgument(!first.startsWith("//"), "first path doesnt start with '//'. Miss bucket");
         // see tests org.carlspring.cloud.storage.s3fs.Path.EndsWithTest#endsWithRelativeBlankAbsolute()
 

src/main/java/org/carlspring/cloud/storage/s3fs/util/S3Utils.java

@@ -164,7 +164,8 @@ public S3BasicFileAttributes getS3FileAttributes(S3Path s3Path)
     }
 
     /**
-     * get the S3PosixFileAttributes for a S3Path
+     * Get the S3PosixFileAttributes for a S3Path
+     * This requires `s3:GetBucketAcl` and `s3:GetObjectAcl`
      *
      * @param s3Path Path mandatory not null
      * @return S3PosixFileAttributes never null

src/test/java/org/carlspring/cloud/storage/s3fs/FileSystemsITTest.java → src/test/java/org/carlspring/cloud/storage/s3fs/FileSystemsIT.java

@@ -1,5 +1,6 @@
 package org.carlspring.cloud.storage.s3fs;
 
+import org.carlspring.cloud.storage.s3fs.junit.annotations.S3IntegrationTest;
 import org.carlspring.cloud.storage.s3fs.util.EnvironmentBuilder;
 
 import java.io.IOException;
@@ -9,14 +10,13 @@
 import java.nio.file.FileSystems;
 
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Tag;
 import org.junit.jupiter.api.Test;
 import static org.carlspring.cloud.storage.s3fs.util.S3EndpointConstant.S3_GLOBAL_URI_IT;
 import static org.junit.jupiter.api.Assertions.assertNotSame;
 import static org.junit.jupiter.api.Assertions.assertSame;
 
-@Tag("s3-integration-test")
-class FileSystemsITTest
+@S3IntegrationTest
+class FileSystemsIT
 {
 
     private static final URI uriEurope = URI.create("s3://s3-eu-west-1.amazonaws.com/");