code: public Optional<Path> captureArtifact(Throwable reason) {
          if (! provider.canGetArtifact(getInstance())) {
              return Optional.absent();
          }
          
          byte[] artifact = provider.getArtifact(getInstance(), reason);
          if ((artifact == null) || (artifact.length == 0)) {
              return Optional.absent();
          }
          
          Path collectionPath = getCollectionPath();
          if (!collectionPath.toFile().exists()) {
              try {
                  Files.createDirectories(collectionPath);
              } catch (IOException e) {
                  if (provider.getLogger() != null) {
                      String messageTemplate = "Unable to create collection directory ({}); no artifact was captured";
                      provider.getLogger().warn(messageTemplate, collectionPath, e);
                  }
                  return Optional.absent();
              }
          }
          
          Path artifactPath;
          try {
              artifactPath = PathUtils.getNextPath(
                              collectionPath, 
                              getArtifactBaseName(), 
                              provider.getArtifactExtension());
          } catch (IOException e) {
              if (provider.getLogger() != null) {
                  provider.getLogger().warn("Unable to get output path; no artifact was captured", e);
              }
              return Optional.absent();
          }
          
          try {
              if (provider.getLogger() != null) {
                  provider.getLogger().info("Saving captured artifact to ({}).", artifactPath);
              }
              Files.write(artifactPath, artifact);
          } catch (IOException e) {
              if (provider.getLogger() != null) {
                  provider.getLogger().warn("I/O error saving to ({}); no artifact was captured", artifactPath, e);
              }
              return Optional.absent();
          }
          
          recordArtifactPath(artifactPath);
          return Optional.of(artifactPath);
      }
docs: Capture artifact from the current test result context.
  
  @param reason impetus for capture request; may be 'null'
  @return (optional) path at which the captured artifact was stored