From c534ad2cbd9ce38d33cdeaee134869afd430876d Mon Sep 17 00:00:00 2001 From: Aiqiao Yan Date: Thu, 7 May 2020 15:03:20 -0400 Subject: [PATCH] Add docs and tests --- .github/workflows/cache-tests.yml | 61 +++++++++++++++++++ README.md | 4 +- packages/cache/CONTRIBUTIONS.md | 0 packages/cache/README.md | 28 +++++++++ .../cache/__tests__/__fixtures__/action.yml | 5 ++ .../cache/__tests__/__fixtures__/index.js | 5 ++ packages/cache/package-lock.json | 54 ++++++++++++++++ scripts/create-cache-files.sh | 17 ++++++ scripts/verify-cache-files.sh | 36 +++++++++++ 9 files changed, 209 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/cache-tests.yml delete mode 100644 packages/cache/CONTRIBUTIONS.md create mode 100644 packages/cache/__tests__/__fixtures__/action.yml create mode 100644 packages/cache/__tests__/__fixtures__/index.js create mode 100755 scripts/create-cache-files.sh create mode 100755 scripts/verify-cache-files.sh diff --git a/.github/workflows/cache-tests.yml b/.github/workflows/cache-tests.yml new file mode 100644 index 00000000..aa382ffc --- /dev/null +++ b/.github/workflows/cache-tests.yml @@ -0,0 +1,61 @@ +name: cache-unit-tests +on: push + +jobs: + build: + name: Build + + strategy: + matrix: + runs-on: [ubuntu-latest, windows-latest, macOS-latest] + fail-fast: false + + runs-on: ${{ matrix.runs-on }} + + steps: + - name: Checkout + uses: actions/checkout@v2 + + - name: Set Node.js 12.x + uses: actions/setup-node@v1 + with: + node-version: 12.x + + # In order to save & restore cache artifacts from a shell script, certain env variables need to be set that are only available in the + # node context. This runs a local action that gets and sets the necessary env variables that are needed + - name: Set env variables + uses: ./packages/cache/__tests__/__fixtures__/ + + # Need root node_modules because certain npm packages like jest are configured for the entire repository and it won't be possible + # without these to just compile the cache package + - name: Install root npm packages + run: npm ci + + - name: Compile cache package + run: | + npm ci + npm run tsc + working-directory: packages/cache + + - name: Generate files in working directory + shell: bash + run: scripts/create-cache-files.sh ${{ runner.os }} test-cache + + - name: Generate files outside working directory + shell: bash + run: scripts/create-cache-files.sh ${{ runner.os }} ~/test-cache + + # We're using node -e to call the functions directly available in the @actions/cache package + - name: Save cache using saveCache() + run: | + node -e "Promise.resolve(require('./packages/cache/lib/cache').saveCache(['test-cache','~/test-cache'],'test-${{ runner.os }}-${{ github.run_id }}'))" + + - name: Restore cache using restoreCache() + run: | + node -e "Promise.resolve(require('./packages/cache/lib/cache').restoreCache(['test-cache','~/test-cache'],'test-${{ runner.os }}-${{ github.run_id }}'))" + + - name: Verify cache + shell: bash + run: | + scripts/verify-cache-files.sh ${{ runner.os }} test-cache + scripts/verify-cache-files.sh ${{ runner.os }} ~/test-cache \ No newline at end of file diff --git a/README.md b/README.md index df36e70b..4ffb0d44 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,8 @@ $ npm install @actions/io --save Provides functions for downloading and caching tools. e.g. setup-* actions. Read more [here](packages/tool-cache) +See @actions/cache for caching workflow dependencies. + ```bash $ npm install @actions/tool-cache --save ``` @@ -84,7 +86,7 @@ $ npm install @actions/artifact --save :dart: [@actions/cache](packages/cache) -Provides functions to cache dependencies and build outputs to improve workflow execution time.. Read more [here](packages/cache) +Provides functions to cache dependencies and build outputs to improve workflow execution time. Read more [here](packages/cache) ```bash $ npm install @actions/cache --save diff --git a/packages/cache/CONTRIBUTIONS.md b/packages/cache/CONTRIBUTIONS.md deleted file mode 100644 index e69de29b..00000000 diff --git a/packages/cache/README.md b/packages/cache/README.md index 402a7f50..f15d0b16 100644 --- a/packages/cache/README.md +++ b/packages/cache/README.md @@ -6,8 +6,36 @@ #### Restore Cache +Restores a cache based on `key` and `restoreKeys` to the `paths` provided. Function returns the cache key for cache hit and returns undefined if cache not found. + +```js +const cache = require('@actions/cache'); +const paths = [ + 'node_modules', + 'packages/*/node_modules/' +] +const key = 'npm-foobar-d5ea0750' +const restoreKeys = [ + 'npm-foobar-', + 'npm-' +] +const cacheKey = await cache.restoreCache(paths, key, restoreKeys) +``` + #### Save Cache +Saves a cache containing the files in `paths` using the `key` provided. Function returns the cache id if the cache was save succesfully. + +```js +const cache = require('@actions/cache'); +const paths = [ + 'node_modules', + 'packages/*/node_modules/' +] +const key = 'npm-foobar-d5ea0750' +const cacheId = await cache.saveCache(paths, key) +``` + ## Additional Documentation See ["Caching dependencies to speed up workflows"](https://help.github.com/github/automating-your-workflow-with-github-actions/caching-dependencies-to-speed-up-workflows). \ No newline at end of file diff --git a/packages/cache/__tests__/__fixtures__/action.yml b/packages/cache/__tests__/__fixtures__/action.yml new file mode 100644 index 00000000..7cd98502 --- /dev/null +++ b/packages/cache/__tests__/__fixtures__/action.yml @@ -0,0 +1,5 @@ +name: 'Set env variables' +description: 'Sets certain env variables so that e2e restore and save cache can be tested in a shell' +runs: + using: 'node12' + main: 'index.js' \ No newline at end of file diff --git a/packages/cache/__tests__/__fixtures__/index.js b/packages/cache/__tests__/__fixtures__/index.js new file mode 100644 index 00000000..82bc6c43 --- /dev/null +++ b/packages/cache/__tests__/__fixtures__/index.js @@ -0,0 +1,5 @@ +// Certain env variables are not set by default in a shell context and are only available in a node context from a running action +// In order to be able to restore and save cache e2e in a shell when running CI tests, we need these env variables set +console.log(`::set-env name=ACTIONS_RUNTIME_URL::${process.env.ACTIONS_RUNTIME_URL}`) +console.log(`::set-env name=ACTIONS_RUNTIME_TOKEN::${process.env.ACTIONS_RUNTIME_TOKEN}`) +console.log(`::set-env name=GITHUB_RUN_ID::${process.env.GITHUB_RUN_ID}`) \ No newline at end of file diff --git a/packages/cache/package-lock.json b/packages/cache/package-lock.json index 569bab49..4e2de82a 100644 --- a/packages/cache/package-lock.json +++ b/packages/cache/package-lock.json @@ -4,6 +4,28 @@ "lockfileVersion": 1, "requires": true, "dependencies": { + "@actions/core": { + "version": "1.2.4", + "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.2.4.tgz", + "integrity": "sha512-YJCEq8BE3CdN8+7HPZ/4DxJjk/OkZV2FFIf+DlZTC/4iBlzYCD5yjRR6eiOS5llO11zbRltIRuKAjMKaWTE6cg==" + }, + "@actions/exec": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@actions/exec/-/exec-1.0.4.tgz", + "integrity": "sha512-4DPChWow9yc9W3WqEbUj8Nr86xkpyE29ZzWjXucHItclLbEW6jr80Zx4nqv18QL6KK65+cifiQZXvnqgTV6oHw==", + "requires": { + "@actions/io": "^1.0.1" + } + }, + "@actions/glob": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/@actions/glob/-/glob-0.1.0.tgz", + "integrity": "sha512-lx8SzyQ2FE9+UUvjqY1f28QbTJv+w8qP7kHHbfQRhphrlcx0Mdmm1tZdGJzfxv1jxREa/sLW4Oy8CbGQKCJySA==", + "requires": { + "@actions/core": "^1.2.0", + "minimatch": "^3.0.4" + } + }, "@actions/http-client": { "version": "1.0.8", "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-1.0.8.tgz", @@ -12,12 +34,44 @@ "tunnel": "0.0.6" } }, + "@actions/io": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/@actions/io/-/io-1.0.2.tgz", + "integrity": "sha512-J8KuFqVPr3p6U8W93DOXlXW6zFvrQAJANdS+vw0YhusLIq+bszW8zmK2Fh1C2kDPX8FMvwIl1OUcFgvJoXLbAg==" + }, "@types/uuid": { "version": "3.4.9", "resolved": "https://registry.npmjs.org/@types/uuid/-/uuid-3.4.9.tgz", "integrity": "sha512-XDwyIlt/47l2kWLTzw/mtrpLdB+GPSskR2n/PIcPn+VYhVO77rGhRncIR5GPU0KRzXuqkDO+J5qqrG0Y8P6jzQ==", "dev": true }, + "balanced-match": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz", + "integrity": "sha1-ibTRmasr7kneFk6gK4nORi1xt2c=" + }, + "brace-expansion": { + "version": "1.1.11", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz", + "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==", + "requires": { + "balanced-match": "^1.0.0", + "concat-map": "0.0.1" + } + }, + "concat-map": { + "version": "0.0.1", + "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", + "integrity": "sha1-2Klr13/Wjfd5OnMDajug1UBdR3s=" + }, + "minimatch": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.0.4.tgz", + "integrity": "sha512-yJHVQEhyqPLUTgt9B83PXu6W3rx4MvvHvSUvToogpwoGDOUQ+yDrR0HRot+yOCdCO7u4hX3pWft6kWBBcqh0UA==", + "requires": { + "brace-expansion": "^1.1.7" + } + }, "tunnel": { "version": "0.0.6", "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz", diff --git a/scripts/create-cache-files.sh b/scripts/create-cache-files.sh new file mode 100755 index 00000000..0ce4140f --- /dev/null +++ b/scripts/create-cache-files.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +# Validate args +prefix="$1" +if [ -z "$prefix" ]; then + echo "Must supply prefix argument" + exit 1 +fi + +path="$2" +if [ -z "$path" ]; then + echo "Must supply path argument" + exit 1 +fi + +mkdir -p $path +echo "$prefix $GITHUB_RUN_ID" > $path/test-file.txt diff --git a/scripts/verify-cache-files.sh b/scripts/verify-cache-files.sh new file mode 100755 index 00000000..3ee8a842 --- /dev/null +++ b/scripts/verify-cache-files.sh @@ -0,0 +1,36 @@ +#!/bin/sh + +# Validate args +prefix="$1" +if [ -z "$prefix" ]; then + echo "Must supply prefix argument" + exit 1 +fi + +path="$2" +if [ -z "$path" ]; then + echo "Must specify path argument" + exit 1 +fi + +# Sanity check GITHUB_RUN_ID defined +if [ -z "$GITHUB_RUN_ID" ]; then + echo "GITHUB_RUN_ID not defined" + exit 1 +fi + +# Verify file exists +file="$path/test-file.txt" +echo "Checking for $file" +if [ ! -e $file ]; then + echo "File does not exist" + exit 1 +fi + +# Verify file content +content="$(cat $file)" +echo "File content:\n$content" +if [ -z "$(echo $content | grep --fixed-strings "$prefix $GITHUB_RUN_ID")" ]; then + echo "Unexpected file content" + exit 1 +fi