From f80df59796147ceff53f6b2111cfeb6ecb0265fa Mon Sep 17 00:00:00 2001 From: Ab <219340+abdala@users.noreply.github.com> Date: Mon, 7 Oct 2024 12:58:40 +0000 Subject: [PATCH 1/2] Create jekyll-gh-pages.yml --- .github/workflows/jekyll-gh-pages.yml | 53 +++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .github/workflows/jekyll-gh-pages.yml diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml new file mode 100644 index 0000000..889581b --- /dev/null +++ b/.github/workflows/jekyll-gh-pages.yml @@ -0,0 +1,53 @@ +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll with GitHub Pages dependencies preinstalled + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + paths: + - "site/**" + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + uses: actions/jekyll-build-pages@v1 + with: + source: ./site + destination: ./_site + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From d5f06d28d177efc48c32d8ab5815d18ac0316fc9 Mon Sep 17 00:00:00 2001 From: Ab C <219340+abdala@users.noreply.github.com> Date: Tue, 8 Oct 2024 11:38:11 +0200 Subject: [PATCH 2/2] Add documentation --- .github/workflows/jekyll-gh-pages.yml | 4 +- docs/.gitignore | 2 + docs/Gemfile | 7 ++ docs/Gemfile.lock | 94 +++++++++++++++++++++++++++ docs/_config.yml | 11 ++++ docs/docs/dtc.md | 57 ++++++++++++++++ docs/docs/dtc/configuration.md | 37 +++++++++++ docs/docs/dtc/quick-start.md | 56 ++++++++++++++++ docs/index.md | 22 +++++++ 9 files changed, 288 insertions(+), 2 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock create mode 100644 docs/_config.yml create mode 100644 docs/docs/dtc.md create mode 100644 docs/docs/dtc/configuration.md create mode 100644 docs/docs/dtc/quick-start.md create mode 100644 docs/index.md diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml index 889581b..0a6044c 100644 --- a/.github/workflows/jekyll-gh-pages.yml +++ b/.github/workflows/jekyll-gh-pages.yml @@ -6,7 +6,7 @@ on: push: branches: ["main"] paths: - - "site/**" + - "docs/**" # Allows you to run this workflow manually from the Actions tab workflow_dispatch: @@ -35,7 +35,7 @@ jobs: - name: Build with Jekyll uses: actions/jekyll-build-pages@v1 with: - source: ./site + source: ./docs destination: ./_site - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e494c5f --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +_site +.jekyll-cache diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..c00a47a --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,7 @@ +source 'https://rubygems.org' + +gem "jekyll", "~> 4.3.4" # installed by `gem jekyll` +# gem "webrick" # required when using Ruby >= 3 and Jekyll <= 4.2.2 + +gem "just-the-docs", "0.10.0" # pinned to the current release +# gem "just-the-docs" # always download the latest release \ No newline at end of file diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..7eb307e --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,94 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + bigdecimal (3.1.8) + colorator (1.1.0) + concurrent-ruby (1.3.4) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.17.0-arm64-darwin) + ffi (1.17.0-x86_64-linux-gnu) + ffi (1.17.0-x86_64-linux-musl) + forwardable-extended (2.6.0) + google-protobuf (4.28.1-arm64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.28.1-x86_64-linux) + bigdecimal + rake (>= 13) + http_parser.rb (0.8.0) + i18n (1.14.6) + concurrent-ruby (~> 1.0) + jekyll (4.3.4) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + just-the-docs (0.10.0) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (6.0.1) + rake (13.2.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.3.7) + rouge (4.3.0) + safe_yaml (1.0.5) + sass-embedded (1.78.0) + google-protobuf (~> 4.27) + rake (>= 13) + sass-embedded (1.78.0-arm64-darwin) + google-protobuf (~> 4.27) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.6.0) + webrick (1.8.1) + +PLATFORMS + arm64-darwin + x86_64-linux-gnu + x86_64-linux-musl + +DEPENDENCIES + jekyll (~> 4.3.4) + just-the-docs (= 0.10.0) + +BUNDLED WITH + 2.5.9 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..18454ce --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,11 @@ +title: CustomerGauge +description: CustomerGauge public node packages documentation +theme: just-the-docs + +url: https://cgauge.github.io/packages + +mermaid: + version: "11.3.0" + +aux_links: + Github: https://github.com/cgauge/packages diff --git a/docs/docs/dtc.md b/docs/docs/dtc.md new file mode 100644 index 0000000..bcac390 --- /dev/null +++ b/docs/docs/dtc.md @@ -0,0 +1,57 @@ +--- +title: DTC +layout: default +nav_order: 2 +--- + +# Declarative Test Cases + +## Introduction + +Declarative Test Case was created to avoid writing code to test the code (in the end, who tests the test?). The main idea is to have a similar way of thinking while writing tests. Using the same data and structure format, something that can be shared between people with different knowledge level and abilities. + +The executing and plugins flow follow the Arrange-Act-Assert pattern: + +```mermaid +graph TD; + accTitle: Arrange-Act-Assert + accDescr: Test steps + Arrange[Arrange inputs and targets] + Act[Act on the target behavior] + Assert[Assert expected outcomes] + Arrange-->Act; + Act-->Assert; +``` + +# Architecture + +The library architecture is divided in four main parts: Loader, Runner, Test Types and Plugins + +```mermaid +flowchart LR + accTitle: Architecture + accDescr: Executing flow + Loader-->Files@{ shape: processes, label: "Files" } + subgraph Runner + subgraph Test Type Plugins + Arrange-->Act + Act-->Assert + end + end + Files-->Runner +``` + +## Loader + +By default DTC loads Javascript files expecting the content to be default exported, but you can basically load any file type by configuring a custom loader. + +## Runner + +By default DTC use Node Native Test Runner Javascript, but it is also flexible to be configured to use Jest, Playwright or any other Test Runner. + +## Default test types + +- Unit: it runs small set of code +- Narrow: for integration tests mocking network, like HTTP calls +- Broad: for integration tests using network + diff --git a/docs/docs/dtc/configuration.md b/docs/docs/dtc/configuration.md new file mode 100644 index 0000000..d2f27b4 --- /dev/null +++ b/docs/docs/dtc/configuration.md @@ -0,0 +1,37 @@ +--- +title: Configuration +layout: default +parent: DTC +nav_order: 2 +--- + +# Configuration + +It is possible to configure custom loaders, runners, test types and plugins. + +## Custom configuration + +```js +// dtc.config.js +export default { + loader: async (filePath) => customLoader(filePath), + runner: new CustomTestRunner(), + plugins: { + unit: [new CustomPlugin()], + customTestType: [new CustomPlugin(), new AnotherPlugin()], + }, + testRegex: /.*\.dtc\.[jt]s?$/ +} +``` + +## Using a configuration + +```sh +npx dtc -c dtc.config.js +``` + +## Executing a custom test type + +```sh +npx dtc -c dtc.config.js -t customTestType +``` diff --git a/docs/docs/dtc/quick-start.md b/docs/docs/dtc/quick-start.md new file mode 100644 index 0000000..ee72825 --- /dev/null +++ b/docs/docs/dtc/quick-start.md @@ -0,0 +1,56 @@ +--- +title: Quick Start +layout: default +parent: DTC +nav_order: 1 +--- + +# Quick Start + +## Installation + +```sh +npm install -D @cgauge/dtc +``` + +### Target file + +```js +// hello.js +export const greeting = (name) => `Hello ${name}` +``` + +### Test case +```js +// hello.dtc.js +export default { + name: 'My first test case', + unit: { + act: { + import: 'greeting', + from: './hello.js', + arguments: ['World'] + }, + assert: 'Hello World' + } +} +``` + +### Executing + +```sh +npx dtc +``` + +### Result + +```sh +✔ My first test case +ℹ tests 1 +ℹ suites 0 +ℹ pass 1 +ℹ fail 0 +ℹ cancelled 0 +ℹ skipped 0 +ℹ todo 0 +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..8014158 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,22 @@ +--- +title: Home +layout: home +nav_order: 1 +--- + +# CustomerGauge Public Packages + +- DTC - Declarative Test Cases +- DTC AWS Plugin - Interact with AWS services +- DTC MySQL Plugin - Interact and Mock MySQL calls +- DTC Playwright Plugin - Test Runner and Interaction +- Nock AWS - Helper to mock AWS API calls +- YAML - YAML parse with extra tags + +## Contributing + +Contributions are always welcome, please have a look at our issues to see if there's something you could help with. + +## License + +All packages are licensed under LGPLv3 license.