diff --git a/.circleci/README.md b/.circleci/README.md new file mode 100755 index 0000000..bf47989 --- /dev/null +++ b/.circleci/README.md @@ -0,0 +1,33 @@ +# Orb Development Pipeline + +This configuration file uses [orb-tools orb](https://circleci.com/developer/orbs/orb/circleci/orb-tools) version 10 to automatically _pack_, _test_, and _publish_ CircleCI orbs using this project structure. View the comments within the config file for a full break down + +## Overview: + +**Imported Orbs** + +Both orb-tools and a development version of your orb will be imported into the config. On the first run, a `dev:alpha` development tag _must_ exist on your orb, but will be handled automatically from there on. + +**Jobs** + +In the _jobs_ key, you will define _integration tests_. These jobs will utilize the functionality of your orb at run-time and attempt to validate their usage with live examples. Integration tests can be an excellent way of determining issues with parameters and run-time execution. + +### Workflows + +There are two workflows which automate the pack, test, and publishing process. + +**test-pack** + +This is the first of the two workflows run. This workflow is responsible for any testing or prepping prior to integration tests. This is where linting occurs, shellchecking, BATS tests, or anything else that can be be tested without the need for further credentials. + +This Workflow will be placed on _hold_ prior to publishing a new development version of the orb (based on this commit), as this step requires access to specific publishing credentials. + +This allows users to fork the orb repository and begin the pipeline, while the code-owners review that the code is safe to test in an environment where publishing keys will be present. + +Once approved, the development version of the orb will publish and the _trigger-integration-tests-workflow_ job will run, kicking off the next workflow + +**integration-test_deploy** + +The second and final workflow is manually triggered by the _trigger-integration-tests-workflow_ job. In this run, the development version of the orb that was just published will be imported, and the integration tests will run. + +When running on the `master` branch (after merging to `master`), the workflow will additionally publish your new production orb. \ No newline at end of file diff --git a/.circleci/config.yml b/.circleci/config.yml index 6f98693..e700f05 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,13 +1,90 @@ -# Use the latest 2.1 version of CircleCI pipeline process engine. See: https://circleci.com/docs/2.0/configuration-reference version: 2.1 -# Use a package of configuration called an orb. + orbs: - # Declare a dependency on the welcome-orb - welcome: circleci/welcome-orb@0.4.1 -# Orchestrate or schedule a set of jobs + civis-integrations-sdk-security: civisanalytics/civis-integrations-sdk-security-orb@<> + orb-tools: circleci/orb-tools@10.0 + shellcheck: circleci/shellcheck@2.0 + +# Pipeline Parameters +## These parameters are used internally by orb-tools. Skip to the Jobs section. +parameters: + run-integration-tests: + description: An internal flag to prevent integration test from running before a development version has been created. + type: boolean + default: false + dev-orb-version: + description: > + The development version of the orb to test. + This value is automatically adjusted by the "trigger-integration-tests-workflow" job to correspond with the specific version created by the commit and should not be edited. + A "dev:alpha" version must exist for the initial pipeline run. + type: string + default: "dev:alpha" + +jobs: + # Define one or more jobs which will utilize your orb's commands and parameters to validate your changes. + integration-test-1: + docker: + - image: cimg/base:stable + steps: + - checkout + workflows: - # Name the workflow "welcome" - welcome: - # Run the welcome/run job in its own container + # Prior to producing a development orb (which requires credentials) basic validation, linting, and even unit testing can be performed. + # This workflow will run on every commit + test-pack: + unless: << pipeline.parameters.run-integration-tests >> jobs: - - welcome/run + - orb-tools/lint # Lint Yaml files + - orb-tools/pack # Pack orb source + - shellcheck/check: + dir: ./src/scripts + exclude: SC2148 + # Publish development version(s) of the orb. + - orb-tools/publish-dev: + orb-name: civisanalytics/civis-integrations-sdk-security-orb + # Must be a context stored at https://app.circleci.com/settings/organization/github/civisanalytics/contexts + context: civis-integrations-sdk-security-orb + requires: + - orb-tools/lint + - orb-tools/pack + - shellcheck/check + # Trigger an integration workflow to test the + # dev:${CIRCLE_SHA1:0:7} version of your orb + - orb-tools/trigger-integration-tests-workflow: + name: trigger-integration-dev + context: civis-integrations-sdk-security-orb + requires: + - orb-tools/publish-dev + + # This `integration-test_deploy` workflow will only run + # when the run-integration-tests pipeline parameter is set to true. + # It is meant to be triggered by the "trigger-integration-tests-workflow" + # job, and run tests on @dev:${CIRCLE_SHA1:0:7}. + integration-test_deploy: + when: << pipeline.parameters.run-integration-tests >> + jobs: + # Run any integration tests defined within the `jobs` key. + - integration-test-1 + # Publish a semver version of the orb. relies on + # the commit subject containing the text "[semver:patch|minor|major|skip]" + # as that will determine whether a patch, minor or major + # version will be published or if publishing should + # be skipped. + # e.g. [semver:patch] will cause a patch version to be published. + - orb-tools/dev-promote-prod-from-commit-subject: + orb-name: civisanalytics/civis-integrations-sdk-security-orb + context: civis-integrations-sdk-security-orb + add-pr-comment: true + fail-if-semver-not-indicated: true + publish-version-tag: true + requires: + - integration-test-1 + filters: + branches: + # Any PR *to* one of these branches should trigger a production release. + # Assuming both the commit and PR are tagged appropriately (l.e. [semver:patch], etc.) + # See https://circleci.com/docs/2.0/creating-orbs/#issue-a-new-release + only: + - master + - main + - de1133_initial_orb_setup diff --git a/.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST.md b/.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST.md new file mode 100755 index 0000000..14b340e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST.md @@ -0,0 +1,37 @@ + +**SEMVER Update Type:** +- [ ] Major +- [ ] Minor +- [ ] Patch + +## Description: + + + +## Motivation: + + + + **Closes Issues:** +- ISSUE URL + +## Checklist: + + + +- [ ] All new jobs, commands, executors, parameters have descriptions. +- [ ] Security: This has security implications. + - [ ] This PR does not require security review. These changes are part of a project plan that has already undergone security review. The link is provided below. + - [ ] This PR requires security review. The `security` label is attached to this PR and a review from `Security Team` will be requested. +- [ ] Testing: How did you test this change (unit tests, acceptance tests, etc.)? Did you do any manual testing? +- [ ] Usage Example version numbers have been updated. +- [ ] Changelog has been updated. diff --git a/.gitignore b/.gitignore new file mode 100755 index 0000000..1600ed4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +# orb.yml is "packed" from source, and not published directly from the repository. +orb.yml + +# Other +.DS_Store +*.DS_Store +.idea diff --git a/.yamllint b/.yamllint new file mode 100755 index 0000000..c9a8a2e --- /dev/null +++ b/.yamllint @@ -0,0 +1,7 @@ +extends: relaxed + +rules: + line-length: + max: 200 + allow-non-breakable-inline-mappings: true + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..63e6450 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,17 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + + +## [1.0.1] - 2021-05-07 +### Added + - Initial release, consists of a security_checks command which runs flake8, safety, and bandit. + - Clean up generic documentation, CHANGELOG, and README files to be specific to this project. + - Starting at 1.0.1 to align with CircleCI version, moving forward. + + +[1.0.1]: GITHUB TAG URL diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..22d817a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,50 @@ +# Contributor Code of Conduct + +As contributors and maintainers of this project, and in the interest of +fostering an open and welcoming community, we pledge to respect all people who +contribute through reporting issues, posting feature requests, updating +documentation, submitting pull requests or patches, and other activities. + +We are committed to making participation in this project a harassment-free +experience for everyone, regardless of level of experience, gender, gender +identity and expression, sexual orientation, disability, personal appearance, +body size, race, ethnicity, age, religion, or nationality. + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery +* Personal attacks +* Trolling or insulting/derogatory comments +* Public or private harassment +* Publishing other's private information, such as physical or electronic + addresses, without explicit permission +* Other unethical or unprofessional conduct + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +By adopting this Code of Conduct, project maintainers commit themselves to +fairly and consistently applying these principles to every aspect of managing +this project. Project maintainers who do not follow or enforce the Code of +Conduct may be permanently removed from the project team. + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting a project maintainer at opensource@civisanalytics.com. +All complaints will be reviewed and investigated and will result in a response +that is deemed necessary and appropriate to the circumstances. Maintainers are +obligated to maintain confidentiality with regard to the reporter of an +incident. + + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 1.3.0, available at +[http://contributor-covenant.org/version/1/3/0/][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/3/0/ \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..405a2b9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,29 @@ +BSD 3-Clause License + +Copyright (c) 2021, Civis Analytics +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived from + this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md index 5f334c7..1ba36ff 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,36 @@ -# civis-integrations-sdk-security-orb -A CircleCI orb with some common security checks for Python repositories. +# Orb Project Template + + +This repo contains an orb with security checks that we wish to include on all future civis-integrations-sdk repositores. + +Additional READMEs are available in each directory. + + +## Resources + +[CircleCI Orb Registry Page](https://circleci.com/orbs/registry/orb/civisanalytics/civis-integrations-sdk-security-orb) - The official registry page of this orb for all versions, executors, commands, and jobs described. +[CircleCI Orb Docs](https://circleci.com/docs/2.0/orb-intro/#section=configuration) - Docs for using and creating CircleCI Orbs. + +### How to Publish +* Create and push a branch with your new features. +* When ready to publish a new production version, create a Pull Request from _feature branch_ to `main`. +* The title of the pull request must contain a special semver tag: `[semver:]` where `` is replaced by one of the following values. + +| Increment | Description| +| ----------| -----------| +| major | Issue a 1.0.0 incremented release| +| minor | Issue a x.1.0 incremented release| +| patch | Issue a x.x.1 incremented release| +| skip | Do not issue a release| + +Example: `[semver:major]` + +* Squash and merge. Ensure the semver tag is preserved and entered as a part of the commit message. +* On merge, after manual approval, the orb will automatically be published to the Orb Registry. + + +For further questions/comments about this or other orbs, visit the Orb Category of [CircleCI Discuss](https://discuss.circleci.com/c/orbs). + diff --git a/src/@orb.yml b/src/@orb.yml new file mode 100755 index 0000000..5bf68e2 --- /dev/null +++ b/src/@orb.yml @@ -0,0 +1,8 @@ +version: 2.1 + +description: > + An orb to standardize security checks for Civis circleCI pipelines + +# This information will be displayed in the orb registry and is not mandatory. +display: + source_url: "https://www.github.com/civisanalytics/civis-integrations-sdk-security-orb" diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..5b96be4 --- /dev/null +++ b/src/README.md @@ -0,0 +1,26 @@ +# Orb Source + +Orbs are shipped as individual `orb.yml` files, however, to make development easier, it is possible to author an orb in _unpacked_ form, which can be _packed_ with the CircleCI CLI and published. + +The default `.circleci/config.yml` file contains the configuration code needed to automatically pack, test, and deploy and changes made to the contents of the orb source in this directory. + +## @orb.yml + +This is the entry point for our orb "tree", which becomes our `orb.yml` file later. + +Within the `@orb.yml` we generally specify 4 configuration keys + +**Keys** + +1. **version** + Specify version 2.1 for orb-compatible configuration `version: 2.1` +2. **description** + Give your orb a description. Shown within the CLI and orb registry +3. **display** + Specify the `home_url` referencing documentation or product URL, and `source_url` linking to the orb's source repository. +4. **orbs** + (optional) Some orbs may depend on other orbs. Import them here. + +## See: + - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) + - [Reusable Configuration](https://circleci.com/docs/2.0/reusing-config) \ No newline at end of file diff --git a/src/commands/README.md b/src/commands/README.md new file mode 100644 index 0000000..7c4373b --- /dev/null +++ b/src/commands/README.md @@ -0,0 +1,10 @@ +# Commands + +Easily add and author [Reusable Commands](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-commands) to the `src/commands` directory. + +Each _YAML_ file within this directory will be treated as an orb command, with a name which matches its filename. + + +## See: + - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) + - [How to author commands](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-commands) diff --git a/src/commands/security_checks.yml b/src/commands/security_checks.yml new file mode 100644 index 0000000..4e3c683 --- /dev/null +++ b/src/commands/security_checks.yml @@ -0,0 +1,52 @@ +description: > + This command runs flake8 and security checks on a repo. +parameters: + dir: + description: the directory to run tests for + type: string + default: . + exclude_dirs: + description: a comma-separated list of directories or subfolders to exclude, i.e. "tests,dev" + type: string + default: "" +steps: + - run: + name: Create Environment + command: | + python3 -m venv security_checks_venv/ + working_directory: << parameters.dir >> + - run: + name: Run flake8 + command: | + source security_checks_venv/bin/activate + pip install flake8 + EXCLUDE_DIRS='<< parameters.exclude_dirs >>' + EXCLUDE_DIR_COMMANDS="./security_checks_venv" + IFS=',' + for TEMP_EXCLUDE in $EXCLUDE_DIRS; do + IFS='' + EXCLUDE_DIR_COMMANDS=${EXCLUDE_DIR_COMMANDS}",./${TEMP_EXCLUDE}" + done + flake8 --exclude ${EXCLUDE_DIR_COMMANDS} + working_directory: << parameters.dir >> + - run: + name: Run Safety Check + command: | + source security_checks_venv/bin/activate + pip install safety + safety check + working_directory: << parameters.dir >> + - run: + name: Run Bandit Check + command: | + source security_checks_venv/bin/activate + pip install bandit + EXCLUDE_DIRS='<< parameters.exclude_dirs >>' + EXCLUDE_DIR_COMMANDS="*/security_checks_venv/*,*/tests/*" + IFS=',' + for TEMP_EXCLUDE in $EXCLUDE_DIRS; do + IFS='' + EXCLUDE_DIR_COMMANDS=${EXCLUDE_DIR_COMMANDS}",./${TEMP_EXCLUDE}" + done + bandit . -r -ll -x ${EXCLUDE_DIR_COMMANDS} + working_directory: << parameters.dir >> diff --git a/src/examples/README.md b/src/examples/README.md new file mode 100644 index 0000000..73d38b6 --- /dev/null +++ b/src/examples/README.md @@ -0,0 +1,13 @@ +# Usage Examples + +Easily author and add [Usage Examples](https://circleci.com/docs/2.0/orb-author/#providing-usage-examples-of-orbs) to the `src/examples` directory. + +Each _YAML_ file within this directory will be treated as an orb usage example, with a name which matches its filename. + +View the included _[example.yml](./example.yml)_ example. + +Usage examples should contain clear use-case based example configurations for using the orb. + + +## See: + - [Providing Usage examples](https://circleci.com/docs/2.0/orb-author/#providing-usage-examples-of-orbs) \ No newline at end of file diff --git a/src/examples/example.yml b/src/examples/example.yml new file mode 100755 index 0000000..6883178 --- /dev/null +++ b/src/examples/example.yml @@ -0,0 +1,26 @@ +description: > + Sample example description. +# Currently, security_checks is the primary job in this orb. +# security_checks will execute flake8, safety check, and bandit in the directory provided. +usage: + version: 2.1 + orbs: + civis-integrations-sdk-security-orb: civisanalytics/civis-integrations-sdk-security-orb@dev:alpha + jobs: + civis_security_orb: + docker: + - image: circleci/python:3.7 # Change this to match your larger project configuration + steps: + # Before running the security orb, you need to do something to get your code into the environment. + # One way is to directly checkout the code + # - checkout + # Alternatively, in some workflows, code is checked out near the beginning and saved to a cache. + # - restore_cache: + # key: your_project_cache-{{ .Environment.CIRCLE_SHA1 }} + - civis-integrations-sdk-security-orb/security_checks: + dir: ~/my_project # directory where your project is located + exclude_dirs: external_package,tests # directories in your project you wish to exclude + workflows: + use-my-orb: + jobs: + - civis_security_orb diff --git a/src/executors/README.md b/src/executors/README.md new file mode 100644 index 0000000..37c0efb --- /dev/null +++ b/src/executors/README.md @@ -0,0 +1,29 @@ +# Executors + +Easily author and add [Parameterized Executors](https://circleci.com/docs/2.0/reusing-config/#executors) to the `src/executors` directory. + +Each _YAML_ file within this directory will be treated as an orb executor, with a name which matches its filename. + +Executors can be used to parameterize the same environment across many jobs. Orbs nor jobs _require_ executors, but may be helpful in some cases, such as: [parameterizing the Node version for a testing job so that matrix testing may be used](https://circleci.com/orbs/registry/orb/circleci/node#usage-run_matrix_testing). + +View the included _[hello.yml](./hello.yml)_ example. + + +```yaml +description: > + This is a sample executor using Docker and Node. +docker: + - image: 'cimg/node:<>' +parameters: + tag: + default: lts + description: > + Pick a specific circleci/node image variant: + https://hub.docker.com/r/cimg/node/tags + type: string +``` + +## See: + - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) + - [How To Author Executors](https://circleci.com/docs/2.0/reusing-config/#authoring-reusable-executors) + - [Node Orb Executor](https://github.com/CircleCI-Public/node-orb/blob/master/src/executors/default.yml) \ No newline at end of file diff --git a/src/jobs/README.md b/src/jobs/README.md new file mode 100644 index 0000000..5dddab9 --- /dev/null +++ b/src/jobs/README.md @@ -0,0 +1,30 @@ +# Jobs + +Easily author and add [Parameterized Jobs](https://circleci.com/docs/2.0/reusing-config/#authoring-parameterized-jobs) to the `src/jobs` directory. + +Each _YAML_ file within this directory will be treated as an orb job, with a name which matches its filename. + +Jobs may invoke orb commands and other steps to fully automate tasks with minimal user configuration. + +View the included _[hello.yml](./hello.yml)_ example. + + +```yaml + # What will this job do? + # Descriptions should be short, simple, and clear. + Sample description +executor: default +parameters: + greeting: + type: string + default: "Hello" + description: "Select a proper greeting" +steps: + - greet: + greeting: << parameters.greeting >> +``` + +## See: + - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) + - [How To Author Commands](https://circleci.com/docs/2.0/reusing-config/#authoring-parameterized-jobs) + - [Node Orb "test" Job](https://github.com/CircleCI-Public/node-orb/blob/master/src/jobs/test.yml) \ No newline at end of file diff --git a/src/scripts/README.md b/src/scripts/README.md new file mode 100644 index 0000000..5554e19 --- /dev/null +++ b/src/scripts/README.md @@ -0,0 +1,40 @@ +# scripts/ + +This is where any scripts you wish to include in your orb can be kept. This is encouraged to ensure your orb can have all aspects tested, and is easier to author, since we sacrifice most features an editor offers when editing scripts as text in YAML. + +As a part of keeping things seperate, it is encouraged to use environment variables to pass through parameters, rather than using the `<< parameter. >>` syntax that CircleCI offers. + +# Including Scripts + +Utilizing the `circleci orb pack` CLI command, it is possible to import files (such as _shell scripts_), using the `<>` syntax in place of any config key's value. + +```yaml +# commands/greet.yml +description: > + This command echos "Hello World" using file inclusion. +parameters: + to: + type: string + default: "World" + description: "Hello to who?" +steps: + - run: + environment: + PARAM_TO: < + name: Hello < + command: <> + +``` + +```shell +# scripts/greet.sh +Greet() { + echo Hello ${PARAM_TO} +} + +# Will not run if sourced from another script. This is done so this script may be tested. +# View src/tests for more information. +if [[ "$_" == "$0" ]]; then + Greet +fi +``` \ No newline at end of file diff --git a/src/tests/README.md b/src/tests/README.md new file mode 100644 index 0000000..ccd0b07 --- /dev/null +++ b/src/tests/README.md @@ -0,0 +1,92 @@ +# tests/ + +This is where your testing scripts for whichever language is embeded in your orb live, which can be executed locally and within a CircleCI pipeline prior to publishing. + +# Testing Orbs + +This orb is built using the `circleci orb pack` command, which allows the _command_ logic to be separated out into separate _shell script_ `.sh` files. Because the logic now sits in a known and executable language, it is possible to perform true unit testing using existing frameworks such a [BATS-Core](https://github.com/bats-core/bats-core#installing-bats-from-source). + +## **Example _command.yml_** + +```yaml + +description: A sample command + +parameters: + source: + description: "source path parameter example" + type: string + default: src + +steps: + - run: + name: "Ensure destination path" + environment: + ORB_SOURCE_PATH: <> + command: <> +``` + +## **Example _command.sh_** + +```bash + +CreatePackage() { + cd "$ORB_SOURCE_PATH" && make + # Build some application at the source location + # In this example, let's assume given some + # sample application and known inputs, + # we expect a certain logfile would be generated. +} + +# Will not run if sourced from another script. +# This is done so this script may be tested. +if [[ "$_" == "$0" ]]; then + CreatePackage +fi + +``` + +We want our script to execute when running in our CI environment or locally, but we don't want to execute our script if we are testing it. In the case of testing, we only want to source the functions within our script,t his allows us to mock inputs and test individual functions. + +**A POSIX Compliant Source Checking Method:** + +```shell +# Will not run if sourced for bats. +# View src/tests for more information. +TEST_ENV="bats-core" +if [ "${0#*$TEST_ENV}" == "$0" ]; then + RUN CODE +fi +``` + +**Example _command_tests.bats_** + +BATS-Core is a useful testing framework for shell scripts. Using the "source checking" methods above, we can source our shell scripts from within our BATS tests without executing any code. This allows us to call specific functions and test their output. + +```bash +# Runs prior to every test. +setup() { + # Load functions from our script file. + # Ensure the script will not execute as + # shown in the above script example. + source ./src/scripts/command.sh +} + +@test '1: Test Build Results' { + # Mock environment variables or functions by exporting them (after the script has been sourced) + export ORB_SOURCE_PATH="src/my-sample-app" + CreatePackage + # test the results + grep -e 'RESULT="success"' log.txt +} + +``` + +Tests can contain any valid shell code. Any error codes returned during a test will result in a test failure. + +In this example, we grep the contents of `log.txt.` which should contain a `success` result if the `CreatePackage` function we had loaded executed successfully. + +## See: + - [BATS Orb](https://circleci.com/orbs/registry/orb/circleci/bats) + - [Orb Testing CircleCI Docs](https://circleci.com/docs/2.0/testing-orbs) + - [BATS-Core GitHub](https://github.com/bats-core/bats-core)