check/test

In the Ruby-based Magento documentation projects, the content testing is implemented using rake tasks (https://github.com/ruby/rake). There are basic tasks check and test, whereas each runs prerequisite tasks that run actual tests.

There are two simple rules to remember about testing:

1. Before you commit, run rake check. This will run tests on modified files only.
2. After you have committed, run rake test. This will run tests on committed files only.

To see all available tasks, run rake --tasks for shorten descriptions, or rake --describe for full descriptions. You can filter tasks by attaching the filtering phrase to those commands such as rake --tasks check or rake --describe test. To view tasks with prerequisites, run rake --prereqs. For more rake options, use rake --help.

rake check

This task verifies uncommitted files. It is useful when checking only changed files before you commit your changes.

• Markdown files are checked for correspondence to Markdown formatting style declared in rules at _checks/styles/style-rules-dev. We use the mdl tool for this (https://github.com/markdownlint/markdownlint).
• Images are checked for optimization with the image_optim tool (https://github.com/toy/image_optim).

Implementation

rake check is declared in the Rakefile and runs check's dependencies sequentially to check images and Markdown formatting. You can trace the dependencies using the --dry-run option:

$ rake --dry-run check
** Invoke check (first_time)
** Invoke check:image_optim (first_time)
** Execute (dry run) check:image_optim
** Invoke check:mdl (first_time)
** Execute (dry run) check:mdl
** Execute (dry run) check

The output demonstrates that all dependencies are declared with a check namespace. All namespaces are declared in separate .rake files at the rakelib directory.

rake test

This task verifies Markdown and HTML syntax and checks internal links on all files within a repository (i.e committed files [for more details on different areas, refer to What is Git?]).

Runs the Markdown linter (mdl) to check if content of the committed .md files satisfies rules defined in the _checks/styles/style-rules-prod file. If no Markdown issues were found, the task cleans the local site after last build, runs a new build, and checks HTML using html-proofer (https://github.com/gjtorikian/html-proofer) configured at _config.checks.yml. It will generate and launch a report about HTML check. The report will be stored at the tmp/.htmlproofer directory in both Markdown and HTML formats.

Implementation

rake test is declared in the Rakefile and runs test's dependencies sequentially to check images and Markdown formatting. You can trace the dependencies using the --dry-run option:

$ rake test --dry-run
** Invoke test (first_time)
** Invoke test:md (first_time)
** Execute (dry run) test:md
** Invoke test:report (first_time)
** Invoke test:links (first_time)
** Invoke build (first_time)
** Invoke clean (first_time)
** Execute (dry run) clean
** Execute (dry run) build
** Invoke test:links_no_build (first_time)
** Execute (dry run) test:links_no_build
** Execute (dry run) test:links
** Execute (dry run) test:report
** Execute (dry run) test

The output contains dependencies with and without namespaces. The tasks without namespaces are declared at the Rakefile, and the tasks with a test namespace are declared at the rakelib/test.rake file .

Live testing

Each time you run the project for a live preview with rake preview or rake preview:all commands, the project is run in a serving mode by bin/jekyll serve command with appropriate options. This mode triggers a hook _checks/html_check_hook.rb that executes HTML checking after each cycle of regeneration. The hook is enabled by the check_links configuration flag in _config.yml, and can be controlled using _config.local.yml locally when the project is run with rake preview. NOTE: All the patterns excluded in _config.local.yml are automatically excluded from HTML checking. _config.local.yml is in play only when running with rake preview.

GitHub checks

GitHub checks are required for a pull request to succeed for ensuring quality of the content.

Markdown linting test

For each new commit on a pull request, GitHub runs a Markdown linting test workflow to ensure Markdown formatting in the contributed content. The workflow is defined in .github/workflows/main.yml, which is run by GitHub Actions.

Jenkins

The Jenkins check ensures that the content introduced in a pull request is not breaking the site. It runs a Jenkins job in an internal Magento infrastructure. This check is triggered by running tests comment from a Magento Documentation team member. This is usually done when the pull request is ready for merging.