getting-started.md

Getting Started

1. Configuring CI
2. Local installation
3. Making ORCA aware of your package
4. Running automated tests
   1. PHPUnit
   2. Nightwatch.js
   3. Tagging/grouping

Configuring CI

ORCA's primary use case is in a continuous integration workflow, running against pull requests and commits. It provides several scripts in bin/ci corresponding to build phases and steps in GitHub Actions:

• before_install.sh configures the CI environment, installs ORCA, and prepares the SUT.
• install.sh creates the test fixture and places the SUT.
• before_script.sh displays details about the fixture for debugging purposes.
• script.sh runs static code analysis and automated tests.
• before_cache.sh is reserved for future use.
• after_success.sh is reserved for future use.
• after_failure.sh displays debugging information in case of failure.
• after_script.sh conditionally logs the job.

See example/.github/workflows/orca.yml for an example GitHub Actions configuration. Features are explained in the comments.

For more complex testing needs, ORCA commands can be invoked directly. See this this example from Lightning.

See also Continuous integration.

Local installation

ORCA can also be installed and run locally for testing and development. Follow these steps to set it up:

1. Ensure you have PHP 7.4 or later with at least 256 MB of memory allocated to it and Composer installed.

2. Choose a directory to contain your package(s), e.g.:

   PARENT_DIR="$HOME/Projects"

3. Install ORCA and clone your package(s) each into the directory, e.g.:

   composer create-project acquia/orca "${PARENT_DIR}/orca"
   git clone [email protected]:acquia/EXAMPLE.git "${PARENT_DIR}/EXAMPLE"

4. Optionally make the commandline executable globally-accessible...

   • Via symlink, e.g.:

     ln -s /path/to/orca/bin/orca /usr/local/bin/orca

   • Or via alias, e.g.:

     alias orca="/path/to/orca/bin/orca"

     (Add this to your .bash_profile/.bashrc or equivalent to make it permanent.)
     Invoke ORCA from the terminal (bin/orca). Use the --help command option to learn more about the various commands or see how they're used in bin/ci/script.sh. Use the fixture:run-server command to run the web server for local development.

Making ORCA aware of your package

If your package isn't included in the built-in list, ORCA won't know about it, leading to errors like the following:

$ orca init --sut=drupal/example
Error: Invalid value for "--sut" option: "drupal/example".

To make ORCA aware of your package you'll need to dynamically add it to the list using environment variables. Doing this on CI is covered in the jobs.build.env section of the example CI configuration. Locally, you must set the appropriate variable(s) in your terminal session. The assignments can be copied right from your orca.yml. Just prefix them with the export command, e.g.:

export ORCA_PACKAGES_CONFIG_ALTER=../example/tests/packages_alter.yml
# and/or...
export ORCA_PACKAGES_CONFIG=../example/tests/packages.yml

Of course environment variables are ephemeral, so if you want them to persist across sessions, add them to your .bashrc or equivalent.

Running automated tests

PHPUnit

ORCA has out-of-the-box support for PHPUnit in Drupal using core's configuration. Existing tests that work in Drupal should work in ORCA without modification. See a working example.

Nightwatch.js

ORCA has out-of-the-box support for Nightwatch in Drupal using core's configuration. Existing tests that work in Drupal should work in ORCA without modification. This means, among other things, that your tests must be tagged with your package's machine name in order to be discovered. At this time, only the SUT's Nightwatch tests are run. See a working example.

Tagging/grouping

ORCA uses groups for PHPUnit to determine which tests to run when, as depicted in the table below. Nightwatch testing only runs on the SUT and does not respect these tags at this time.

	(Default)	orca_public	orca_ignore
Isolated tests (own)	✓	✓
Integrated tests (own)	✓	✓
Integrated tests (others')		✓

The default behavior is to run a test only when the package providing it is the SUT--not when it is merely included in another package's test fixture. Any test not designated public or ignored is so treated. Such tests are referred to as "private tests". This should be considered the correct choice for most tests--particularly for features that involve little or no risk of conflict with other company packages, including isolated unit tests by definition.

Public PHPUnit tests (orca_public) are always run, including when testing packages other than the one providing them. Acquia's implementation, for example, a public PHPUnit test provided by Lightning API will also be run during tests of Acquia Lift, Acquia Purge, and the rest. Public tests thus lengthen builds for all company packages and should be used judiciously. Reserve them for high value features with meaningful risk of being broken by other packages, and make them as fast as possible.

Ignored tests (orca_ignore) are "ignored" and never run by ORCA. Tests should be ignored when they depend upon setup or preconditions that ORCA doesn't provide, such as a fixture with unique dependencies or a database populated by SQL dump. Once ignored, such tests can be scripted to run apart from ORCA after custom setup. In practice, it should rarely be necessary to ignore a test, as most setup and teardown can be accomplished through PHPUnit template methods.

---

README | Understanding ORCA | Getting Started | CLI Commands | Advanced Usage | Project Glossary | FAQ | Contribution Guide