Added the ability to alter the active packages specification (#17)

* Added the ability to add extra packages specification at runtime via environment variable.

* Added the ability to override or remove packages spefication at runtime via environment variable.

* Made documentation footer earier to maintain.

* Documented environment variables.

bin/self-test

@@ -38,4 +38,5 @@ cd ../example
 [[ -z "$TRAVIS" ]] && SUFFIX="-$(date +%Y-%m-%d_%H-%m-%S)" || SUFFIX=""
 ORCA_FIXTURE_DIR="$(cd .. && pwd)/orca-build${SUFFIX}" \
   ORCA_PACKAGES_CONFIG="tests/Fixture/packages.yml" \
+  ORCA_PACKAGES_CONFIG_ALTER="example/tests/packages.yml" \
   ../orca/bin/travis/script drupal/example

config/packages.yml

@@ -1,8 +1,8 @@
 ---
-# An indexed array of Acquia software package data. Each element is an
-# associative array that may contain the following key-value pairs:
-# - "name": (required) The package name, corresponding to the "name" property in
-#   its composer.json file, e.g., "drupal/example".
+# An array of Acquia software package data. Each package datum is keyed by its
+# package name, i.e., the "name" property in its composer.json file, e.g.,
+# "drupal/example", and has a corresponding array value that may contain the
+# following key-value pairs:
 # - "type": (optional) The package type, corresponding to the "type" property in
 #   its composer.json file. Defaults to "drupal-module".
 # - "install_path": (optional) The path the package gets installed at relative
@@ -23,70 +23,70 @@
 #
 # These are converted to \Acquia\Orca\Fixture\Package objects by
 # \Acquia\Orca\Fixture\PackageManager. A different specification can be
-# substituted at runtime using the "ORCA_PACKAGES_CONFIG" environment variable.
-# See config/services.yml for the relevant code or bin/self-test for a usage
+# substituted at runtime using the "ORCA_PACKAGES_CONFIG" environment variable
+# or merged in using the "ORCA_PACKAGES_CONFIG_ALTER" environment variable. See
+# config/services.yml for the relevant code or bin/self-test for a usage
 # example.
--
-  name: acquia/acsf-tools
+acquia/acsf-tools:
   type: drupal-drush
   # acsf-tools specifies an installer-name.
   install_path: drush/Commands/acsf_tools
   version_dev: dev-9.x-dev
--
-  name: acquia/blt
+
+acquia/blt:
   type: composer-plugin
   version: ~10.0
   version_dev: 10.0.x-dev
--
-  name: acquia/drupal-spec-tool
+
+acquia/drupal-spec-tool:
   type: behat-extension
   version_dev: 2.x-dev
-#-
-#  name: drupal/acquia_commercemanager
+
+#drupal/acquia_commercemanager:
 #  url: ../commerce-manager
 #  version_dev: 1.x-dev
--
-  name: drupal/acquia_connector
+
+drupal/acquia_connector:
   url: ../acquia-connector
   version_dev: 1.x-dev
--
-  name: drupal/acquia_contenthub
+
+drupal/acquia_contenthub:
   url: ../content-hub-d8
   version: ~1.0
   version_dev: 1.x-dev
--
-  name: drupal/acquia_lift
+
+drupal/acquia_lift:
   version_dev: 3.x-dev
--
-  name: drupal/acquia_purge
+
+drupal/acquia_purge:
   version_dev: 1.x-dev
-#-
-#  name: drupal/acsf
+
+#drupal/acsf:
 #  version_dev: "*"
--
-  name: drupal/cog
+
+drupal/cog:
   type: drupal-theme
   version_dev: 1.x-dev
--
-  name: drupal/lightning_api
+
+drupal/lightning_api:
   url: ../lightning-api
   version_dev: 3.x-dev
--
-  name: drupal/lightning_core
+
+drupal/lightning_core:
   url: ../lightning-core
   version_dev: 3.x-dev
--
-  name: drupal/lightning_layout
+
+drupal/lightning_layout:
   url: ../lightning-layout
   version_dev: 1.x-dev
--
-  name: drupal/lightning_media
+
+drupal/lightning_media:
   url: ../lightning-media
   version_dev: 3.x-dev
--
-  name: drupal/lightning_workflow
+
+drupal/lightning_workflow:
   url: ../lightning-workflow
   version_dev: 3.x-dev
-#-
-#  name: drupal/media_acquiadam
+
+#drupal/media_acquiadam:
 #  version_dev: 1.x-dev

config/services.yml

@@ -5,6 +5,7 @@ parameters:
   env(ORCA_DRUPAL_CORE_VERSION): ~
   env(ORCA_FIXTURE_DIR): "%app.fixture_dir%"
   env(ORCA_PACKAGES_CONFIG): config/packages.yml
+  env(ORCA_PACKAGES_CONFIG_ALTER): ~
 
   # Static configuration:
   drupal_core_dev_version: 8.6.x-dev
@@ -20,6 +21,7 @@ services:
       $fixture_dir: "%env(ORCA_FIXTURE_DIR)%"
       $project_dir: "%kernel.project_dir%"
       $packages_config: "%env(ORCA_PACKAGES_CONFIG)%"
+      $packages_config_alter: "%env(ORCA_PACKAGES_CONFIG_ALTER)%"
     public: true
 
   Acquia\Orca\:

docs/CONTRIBUTING.md

@@ -27,4 +27,10 @@
 
 ---
 
-[README](README.md) | [Understanding ORCA](understanding-orca.md) | [Getting Started](getting-started.md) | [Project Glossary](glossary.md) | [FAQ](faq.md) | **Contribution Guide**
+[README](README.md)
+| [Understanding ORCA](understanding-orca.md)
+| [Getting Started](getting-started.md)
+| [Advanced Usage](advanced-usage.md)
+| [Project Glossary](glossary.md)
+| [FAQ](faq.md)
+| **Contribution Guide**

docs/README.md

@@ -16,6 +16,7 @@ ORCA (Official Representative Customer Application) is a tool for testing Acquia
 
 * [Understanding ORCA](understanding-orca.md)
 * [Getting Started](getting-started.md)
+* [Advanced Usage](advanced-usage.md)
 * [Project Glossary](glossary.md)
 * [FAQ](faq.md)
 * [Contribution Guide](CONTRIBUTING.md)

docs/advanced-usage.md

@@ -0,0 +1,23 @@
+# Advanced Usage
+
+## Altering ORCA's behavior
+
+Various aspects of ORCA's behavior can be altered at runtime through the use of environment variables. These can be set or exported in a local terminal session or [in various ways on Travis CI](https://docs.travis-ci.com/user/environment-variables/).
+
+* <a name="ORCA_DRUPAL_CORE_VERSION"></a>**`ORCA_DRUPAL_CORE_VERSION`**: Change the version of Drupal core ORCA creates test fixtures with. This can be useful for testing upgrade paths, for example. Acceptable values are any version strings Composer understands, e.g., `8.6.0`, `~8.6`, or `8.6.x-dev`.
+
+* <a name="ORCA_FIXTURE_DIR"></a>**`ORCA_FIXTURE_DIR`**: Change the directory ORCA uses for test fixtures. Acceptable values are any valid, local directory reference, e.g., `/var/www/example`, or `../example`.
+
+* <a name="ORCA_PACKAGES_CONFIG"></a>**`ORCA_PACKAGES_CONFIG`**: Completely replace the list of packages ORCA installs in fixtures and runs tests on. Acceptable values are any valid path to a YAML file relative to ORCA itself, e.g., `../example/tests/packages.yml`. See [`config/packages.yml`](../config/packages.yml) for an example and explanation of the schema.
+
+* <a name="ORCA_PACKAGES_CONFIG_ALTER"></a>**`ORCA_PACKAGES_CONFIG_ALTER`**: Alter the main list of package ORCA installs in fixtures and runs tests on (add, remove, or change packages and their properties). Acceptable values are any valid path to a YAML file relative to ORCA itself, e.g., `../example/tests/packages.yml`. See [`example/tests/packages.yml`](../example/tests/packages.yml) for an example and explanation.
+
+---
+
+[README](README.md)
+| [Understanding ORCA](understanding-orca.md)
+| [Getting Started](getting-started.md)
+| **Advanced Usage**
+| [Project Glossary](glossary.md)
+| [FAQ](faq.md)
+| [Contribution Guide](CONTRIBUTING.md)

docs/faq.md

@@ -49,4 +49,10 @@ Cf. [Why doesn't ORCA enable my submodule?](#why-doesnt-orca-enable-my-submodule
 
 ---
 
-[README](README.md) | [Understanding ORCA](understanding-orca.md) | [Getting Started](getting-started.md) | [Project Glossary](glossary.md) | **FAQ** | [Contribution Guide](CONTRIBUTING.md)
+[README](README.md)
+| [Understanding ORCA](understanding-orca.md)
+| [Getting Started](getting-started.md)
+| [Advanced Usage](advanced-usage.md)
+| [Project Glossary](glossary.md)
+| **FAQ**
+| [Contribution Guide](CONTRIBUTING.md)

docs/getting-started.md

@@ -63,4 +63,10 @@ Ignored tests (`orca_ignore`) are "ignored" and _never_ run by ORCA. Tests shoul
 
 ---
 
-[README](README.md) | [Understanding ORCA](understanding-orca.md) | **Getting Started** | [Project Glossary](glossary.md) | [FAQ](faq.md) | [Contribution Guide](CONTRIBUTING.md)
+[README](README.md)
+| [Understanding ORCA](understanding-orca.md)
+| **Getting Started**
+| [Advanced Usage](advanced-usage.md)
+| [Project Glossary](glossary.md)
+| [FAQ](faq.md)
+| [Contribution Guide](CONTRIBUTING.md)

docs/glossary.md

@@ -87,4 +87,10 @@ In automated testing, a test fixture is all the things we need to have in place
 
 ---
 
-[README](README.md) | [Understanding ORCA](understanding-orca.md) | [Getting Started](getting-started.md) | **Project Glossary** | [FAQ](faq.md) | [Contribution Guide](CONTRIBUTING.md)
+[README](README.md)
+| [Understanding ORCA](understanding-orca.md)
+| [Getting Started](getting-started.md)
+| [Advanced Usage](advanced-usage.md)
+| **Project Glossary**
+| [FAQ](faq.md)
+| [Contribution Guide](CONTRIBUTING.md)

docs/understanding-orca.md

@@ -74,4 +74,10 @@ See [Configuring Travis CI](getting-started.md#configuring-travis-ci).
 
 ---
 
-[README](README.md) | **Understanding ORCA** | [Getting Started](getting-started.md) | [Project Glossary](glossary.md) | [FAQ](faq.md) | [Contribution Guide](CONTRIBUTING.md)
+[README](README.md)
+| **Understanding ORCA**
+| [Getting Started](getting-started.md)
+| [Advanced Usage](advanced-usage.md)
+| [Project Glossary](glossary.md)
+| [FAQ](faq.md)
+| [Contribution Guide](CONTRIBUTING.md)

example/tests/packages.yml

@@ -0,0 +1,10 @@
+# Package data to merge into the main specification at runtime using the
+# "ORCA_PACKAGES_CONFIG_ALTER" environment variable. See config/packages.yml for
+# more information, including the schema.
+---
+# Remove the Bad judgement module.
+drupal/bad_judgement: ~
+
+# Add the Example module.
+drupal/example:
+  version_dev: "*"

src/Fixture/Package.php

@@ -23,15 +23,23 @@ class Package {
    */
   private $fixture;
 
+  /**
+   * The package name.
+   *
+   * @var string
+   */
+  private $packageName;
+
   /**
    * Constructs an instance.
    *
    * @param \Acquia\Orca\Fixture\Fixture $fixture
    *   The fixture.
+   * @param string $package_name
+   *   The package name, corresponding to the "name" property in its
+   *   composer.json file, e.g., "drupal/example".
    * @param array $data
    *   An array of package data that may contain the following key-value pairs:
-   *   - "name": (required) The package name, corresponding to the "name"
-   *     property in its composer.json file, e.g., "drupal/example".
    *   - "type": (optional) The package type, corresponding to the "type"
    *     property in its composer.json file. Defaults to "drupal-module".
    *   - "install_path": (optional) The path the package gets installed at
@@ -48,8 +56,9 @@ class Package {
    *     Composer. Defaults to "*".
    *   - "version": (required) The dev package version to require via Composer.
    */
-  public function __construct(Fixture $fixture, array $data) {
+  public function __construct(Fixture $fixture, string $package_name, array $data) {
     $this->fixture = $fixture;
+    $this->initializePackageName($package_name);
     $this->data = $this->resolveData($data);
   }
 
@@ -65,26 +74,19 @@ public function __construct(Fixture $fixture, array $data) {
   private function resolveData(array $data): array {
     $resolver = (new OptionsResolver())
       ->setDefined([
-        'name',
         'type',
         'install_path',
         'url',
         'version',
         'version_dev',
         'enable',
       ])
-      ->setRequired(['name', 'version_dev'])
+      ->setRequired(['version_dev'])
       ->setDefaults([
         'type' => 'drupal-module',
         'version' => '*',
         'enable' => TRUE,
       ])
-      ->setAllowedTypes('name', 'string')
-      ->setAllowedValues('name', function ($value) {
-        // Require a a full package name: "vendor/project". A simple test for a
-        // forward slash will suffice.
-        return strpos($value, '/') !== FALSE;
-      })
       ->setAllowedTypes('type', 'string')
       ->setAllowedTypes('install_path', 'string')
       ->setAllowedTypes('url', 'string')
@@ -177,7 +179,7 @@ public function getType(): string {
    *   The package name, e.g., "drupal/example".
    */
   public function getPackageName(): string {
-    return $this->data['name'];
+    return $this->packageName;
   }
 
   /**
@@ -209,7 +211,7 @@ public function getPackageStringRecommended(): string {
    *   The project name, e.g., "example".
    */
   public function getProjectName(): string {
-    $package_name_parts = explode('/', $this->data['name']);
+    $package_name_parts = explode('/', $this->packageName);
     return $package_name_parts[count($package_name_parts) - 1];
   }
 
@@ -248,4 +250,22 @@ public function shouldGetEnabled(): bool {
     return $this->data['enable'];
   }
 
+  /**
+   * Initializes the package name.
+   *
+   * @param string $package_name
+   *   The package name.
+   *
+   * @throws \InvalidArgumentException
+   *   In case of an invalid package name.
+   */
+  private function initializePackageName(string $package_name): void {
+    // Require a a full package name: "vendor/project". A simple test for a
+    // forward slash will suffice.
+    if (strpos($package_name, '/') === FALSE) {
+      throw new \InvalidArgumentException("Invalid package name: {$package_name}. Must take the form 'vendor/project'.");
+    }
+    $this->packageName = $package_name;
+  }
+
 }