added Installation heading, a section stated what encompasses a structure tests, additional small tweaks (#14)

Author: aaron-prindle

README.md

@@ -1,63 +1,71 @@
-GCP Structure Tests
+Container Structure Tests
 ====================
 
-The GCP Structure Tests provide a powerful framework to validate the structure 
-of a container image. These tests can be used to check the output of commands 
+The Container Structure Tests provide a powerful framework to validate the structure
+of a container image. These tests can be used to check the output of commands
 in an image, as well as verify metadata and contents of the filesystem.
 
-Tests can be run either through a standalone binary, or through a Docker image as part of a cloudbuild. Download the binary
-[here](https://storage.googleapis.com/container-structure-test/latest/container-structure-test),
+Tests can be run either through a standalone binary, or through a Docker image.
+
+## Installation
+Download the latest binary release [here](https://storage.googleapis.com/container-structure-test/latest/container-structure-test),
 or pull the image at `gcr.io/gcp-runtimes/container-structure-test`.
 **Please note that at this time the binary is only compatible with Linux.**
 
+## Setup
+To use container structure tests to validate your containers, you need the following:
+- The container structure test binary or docker image
+- A container image to test against
+- A test .yaml or .json file with user defined structure tests to run inside of the specified container image
+
 ## Example Run
 An example run of the test framework:
 ```shell
 ./structure-test -test.v -image gcr.io/google-appengine/python \
 python_test_config.yaml
 ```
-This command will run the tests on the GAE Python image, with verbose logging, 
+This command will run the tests on the Google App Engine Python image, with verbose logging,
 using the python_test_config.yaml test config.
 
-Tests within this framework are specified through a YAML or JSON config file, 
-which is provided to the test driver as the last positional argument of the 
-command. Multiple config files may be specified in a single test run. The 
-config file will be loaded in by the test driver, which will execute the tests 
+Tests within this framework are specified through a YAML or JSON config file,
+which is provided to the test driver as the last positional argument of the
+command. Multiple config files may be specified in a single test run. The
+config file will be loaded in by the test driver, which will execute the tests
 in order. Within this config file, four types of tests can be written:
 
 - Command Tests (testing output/error of a specific command issued)
-- File Existence Tests (making sure a file is, or isn't, present in the 
+- File Existence Tests (making sure a file is, or isn't, present in the
 file system of the image)
-- File Content Tests (making sure files in the file system of the image 
+- File Content Tests (making sure files in the file system of the image
 contain, or do not contain, specific contents)
 - Metadata Test, *singular* (making sure certain container metadata is correct)
 
 ## Command Tests
 Command tests ensure that certain commands run properly in the target image.
-Regexes can be used to check for expected or excluded strings in both stdout 
-and stderr. Additionally, any number of flags can be passed to the argument 
+Regexes can be used to check for expected or excluded strings in both stdout
+and stderr. Additionally, any number of flags can be passed to the argument
 as normal.
 
 #### Supported Fields:
 
 This is the current schema version (v2.0.0).
 
 - Name (string, **required**): The name of the test
-- Setup ([][]string, *optional*): A list of commands 
+- Setup ([][]string, *optional*): A list of commands
 (each with optional flags) to run before the actual command under test.
-- Teardown ([][]string, *optional*): A list of commands 
+- Teardown ([][]string, *optional*): A list of commands
 (each with optional flags) to run after the actual command under test.
 - Command (string, **required**): The command to run in the test.
 - Args ([]string, *optional*): The arguments to pass to the command.
-- EnvVars ([]EnvVar, *optional*): A list of environment variables to set for 
+- EnvVars ([]EnvVar, *optional*): A list of environment variables to set for
 the individual test. See the **Environment Variables** section for more info.
-- Expected Output ([]string, *optional*): List of regexes that should 
+- Expected Output ([]string, *optional*): List of regexes that should
 match the stdout from running the command.
-- Excluded Output ([]string, *optional*): List of regexes that should **not** 
+- Excluded Output ([]string, *optional*): List of regexes that should **not**
 match the stdout from running the command.
-- Expected Error ([]string, *optional*): List of regexes that should 
+- Expected Error ([]string, *optional*): List of regexes that should
 match the stderr from running the command.
-- Excluded Error ([]string, *optional*): List of regexes that should **not** 
+- Excluded Error ([]string, *optional*): List of regexes that should **not**
 match the stderr from running the command.
 - Exit Code (int, *optional*): Exit code that the command should exit with.
 
@@ -73,21 +81,21 @@ commandTests:
   command: "apt-get"
   args: ["-qqs", "upgrade"]
   excludedOutput: [".*Inst.*Security.* | .*Security.*Inst.*"]
-  excludedError: [".*Inst.*Security.* | .*Security.*Inst.*"]  
+  excludedError: [".*Inst.*Security.* | .*Security.*Inst.*"]
 ```
 
 
 ## File Existence Tests
-File existence tests check to make sure a specific file (or directory) exist 
-within the file system of the image. No contents of the files or directories 
-are checked. These tests can also be used to ensure a file or directory is 
+File existence tests check to make sure a specific file (or directory) exist
+within the file system of the image. No contents of the files or directories
+are checked. These tests can also be used to ensure a file or directory is
 **not** present in the file system.
 
 #### Supported Fields:
 
 - Name (string, **required**): The name of the test
 - Path (string, **required**): Path to the file or directory under test
-- ShouldExist (boolean, **required**): Whether or not the specified file or 
+- ShouldExist (boolean, **required**): Whether or not the specified file or
 directory should exist in the file system
 - Permissions (string, *optional*): The expected Unix permission string (e.g.
   drwxrwxrwx) of the files or directory.
@@ -102,19 +110,19 @@ fileExistenceTests:
 ```
 
 ## File Content Tests
-File content tests open a file on the file system and check its contents. 
-These tests assume the specified file **is a file**, and that it **exists** 
-(if unsure about either or these criteria, see the above 
-**File Existence Tests** section). Regexes can again be used to check for 
+File content tests open a file on the file system and check its contents.
+These tests assume the specified file **is a file**, and that it **exists**
+(if unsure about either or these criteria, see the above
+**File Existence Tests** section). Regexes can again be used to check for
 expected or excluded content in the specified file.
 
 #### Supported Fields:
 
 - Name (string, **required**): The name of the test
 - Path (string, **required**): Path to the file under test
-- ExpectedContents (string[], *optional*): List of regexes that 
+- ExpectedContents (string[], *optional*): List of regexes that
 should match the contents of the file
-- ExcludedContents (string[], *optional*): List of regexes that 
+- ExcludedContents (string[], *optional*): List of regexes that
 should **not** match the contents of the file
 
 Example:
@@ -172,10 +180,10 @@ licenseTests:
 ```
 
 ### Environment Variables
-A list of environment variables can optionally be specified as part of the 
-test setup. They can either be set up globally (for all test runs), or 
-test-local as part of individual command test runs (see the **Command Tests** 
-section above). Each environment variable is specified as a key-value pair. 
+A list of environment variables can optionally be specified as part of the
+test setup. They can either be set up globally (for all test runs), or
+test-local as part of individual command test runs (see the **Command Tests**
+section above). Each environment variable is specified as a key-value pair.
 Unix-style environment variable substitution is supported.
 
 To specify, add a section like this to your config:
@@ -188,17 +196,21 @@ globalEnvVars:
     value: "/env/bin:$PATH"
 ```
 
+## Running File Tests On Cloudbuild
+
+TODO
+
 
 ## Running File Tests Without Docker
 
-Container images can be represented in multiple formats, and the Docker image 
-is just one of them. At their core, images are just a series of layers, each 
-of which is a tarball, and so can be interacted with without a working Docker 
-daemon. While running command tests currently requires a functioning Docker 
-daemon on the host machine, File Existence/Content tests do not. This can be 
-particularly useful when dealing with images which have been `docker export`ed 
-or saved in a different image format than the Docker format. To run tests 
-without using a Docker daemon, a user can specify a different "driver" to use 
+Container images can be represented in multiple formats, and the Docker image
+is just one of them. At their core, images are just a series of layers, each
+of which is a tarball, and so can be interacted with without a working Docker
+daemon. While running command tests currently requires a functioning Docker
+daemon on the host machine, File Existence/Content tests do not. This can be
+particularly useful when dealing with images which have been `docker export`ed
+or saved in a different image format than the Docker format. To run tests
+without using a Docker daemon, a user can specify a different "driver" to use
 in the tests, with the `-driver` flag.
 
 An example test run with a different driver looks like:
@@ -208,21 +220,21 @@ python_test_config.yaml
 ```
 
 The currently supported drivers in the framework are:
-- `docker`: the default driver. 
+- `docker`: the default driver.
 Supports all tests, and uses the Docker daemon on the host to run them.
-- `tar`: a tar driver, which converts an image to a single tarball before 
+- `tar`: a tar driver, which converts an image to a single tarball before
 interacting with it. Does *not* support command tests.
 
 
 ### Running Structure Tests Through Bazel
-Structure tests can also be run through bazel. 
+Structure tests can also be run through bazel.
 To do so, include the rule definitions in your BUILD file:
 
 ```BUILD
 load("@container-structure-test//:tests.bzl", "structure_test")
 ```
 
-and create a `structure_test` rule, passing in your image and config 
+and create a `structure_test` rule, passing in your image and config
 file as parameters:
 
 ```BUILD
@@ -240,4 +252,4 @@ structure_test(
     config = "testdata/hello.yaml",
     image = ":hello",
 )
-```
+```