{"id":15013927,"url":"https://github.com/puppetlabs/puppetlabs_spec_helper","last_synced_at":"2025-05-14T12:08:20.646Z","repository":{"id":640559,"uuid":"3037349","full_name":"puppetlabs/puppetlabs_spec_helper","owner":"puppetlabs","description":"A set of shared spec helpers specific to Puppetlabs projects","archived":false,"fork":false,"pushed_at":"2025-02-25T12:19:42.000Z","size":923,"stargazers_count":118,"open_issues_count":5,"forks_count":145,"subscribers_count":169,"default_branch":"main","last_synced_at":"2025-03-27T21:05:29.903Z","etag":null,"topics":["hacktoberfest","puppet","rspec-puppet"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-12-22T23:35:46.000Z","updated_at":"2025-02-25T12:19:46.000Z","dependencies_parsed_at":"2023-07-09T12:33:07.079Z","dependency_job_id":"1059fa40-0843-471e-a11d-e08f1bd92ab3","html_url":"https://github.com/puppetlabs/puppetlabs_spec_helper","commit_stats":{"total_commits":512,"total_committers":128,"mean_commits":4.0,"dds":0.89453125,"last_synced_commit":"75239c840c746a5759d6478ee9721ddec7168923"},"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs_spec_helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs_spec_helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs_spec_helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs_spec_helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs_spec_helper/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247086025,"owners_count":20881160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","puppet","rspec-puppet"],"created_at":"2024-09-24T19:44:57.491Z","updated_at":"2025-04-03T22:04:57.317Z","avatar_url":"https://github.com/puppetlabs.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Puppet Labs Spec Helper\n=======================\n\n[![Code Owners](https://img.shields.io/badge/owners-DevX--team-blue)](https://github.com/puppetlabs/puppetlabs_spec_helper/blob/main/CODEOWNERS)\n![ci](https://github.com/puppetlabs/puppetlabs_spec_helper/actions/workflows/ci.yml/badge.svg)\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/puppetlabs/puppetlabs_spec_helper)\n\nThe Short Version\n-----------------\n\nThis repository is meant to provide a single source of truth for how to\ninitialize different Puppet versions for spec testing.\n\nThe common use case is a module such as\n[stdlib](http://forge.puppetlabs.com/puppetlabs/stdlib) that works with many\nversions of Puppet.  The stdlib module should require the spec helper in this\nrepository, which will in turn automatically figure out the version of Puppet\nbeing tested against and perform version specific initialization.\n\nOther \"customers\" that should use this module are:\n\n * [Facter](https://github.com/puppetlabs/facter)\n * [PuppetDB](https://github.com/puppetlabs/puppetdb)\n * [Mount Providers](https://github.com/puppetlabs/puppetlabs-mount_providers)\n\nUsage\n=====\n\nWhen developing or testing modules, simply clone this repository and install the\ngem it contains. The recommended way to do this is using [bundler](http://bundler.io/#getting-started).\n\nExample Gemfile:\n\n    source 'https://rubygems.org'\n    gem 'puppetlabs_spec_helper'\n\nAdd this to your project's spec\\_helper.rb:\n\n    require 'puppetlabs_spec_helper/module_spec_helper'\n\nAdd this to your project's Rakefile:\n\n    require 'puppetlabs_spec_helper/rake_tasks'\n\nAnd run the spec tests:\n\n    $ cd $modulename\n    $ rake spec\n\n\n### Parallel Fixture Downloads\nFixture downloads will now execute in parallel to speed up the testing process. Which can represent \u003e= 600% speed increase (depending on number of threads). You can control the amount of threads by setting the `MAX_FIXTURE_THREAD_COUNT` environment variable\nto a positive integer, the default is currently 10.  We don't suggest going higher than 25 as the gains are marginal due to some repos taking a long time to download.  Please be aware that your internal VCS system may not be able to handle a high load in which case the server would fail to clone the repository. Because of this issue, this setting is tunable via `MAX_FIXTURE_THREAD_COUNT`.\n\nAdditionally, you can also speed up cloning when using the ssh protocol by multiplexing ssh sessions.  Add something similar to your ssh config.\nNote: you may need to change the host if you're using an internal git server.\n\n```shell\nHost github.com\n  ControlMaster auto\n  ControlPath ~/.ssh/ssh-%r@%h:%p\n  ControlPersist yes\n\n```\n\nNote: parallel downloads are available for repositories and forge modules.\n\n### Parallel tests\nIt is also possible to use the `parallel_tests` Gem via the `:parallel_spec` Rake task to run rspec commands in parallel on groups of spec files.\n\nUse of parallelization at this level can result in large performance benefits when the Rspec examples tend to cause a number of large, CPU-intensive catalog compilations to occur.  An example of where this might be the case is in a complex module with a lot of tests or a control repo with many hosts.\n\nBe aware however that in other circumstances this parallelization can result in the tests actually taking longer to run.  The best thing to do is time `rspec spec` and `rspec parallel_spec` and use the parallelization only when there is a clear benefit.\n\nTo enable this feature, add the `parallel_tests` Gem to your project's Gemfile:\n\n    gem 'parallel_tests'\n\nAnd then to run spec tests in parallel:\n\n    $ rake parallel_spec\n\nIssues\n======\n\nPlease file issues against this project at the [Puppet Labs Issue Tracker](https://tickets.puppetlabs.com/browse/MODULES)\n\nThe Long Version\n----------------\n\nPurpose of this Project\n=======================\n\nThis project is intended to serve two purposes:\n\n1. To serve as a bridge between external projects and multiple versions of puppet;\n   in other words, if your project has a dependency on puppet, you shouldn't need\n   to need to worry about the details of how to initialize puppet's state for\n   testing, no matter what version of puppet you are testing against.\n2. To provide some convenience classes / methods for doing things like creating\n   tempfiles, common rspec matchers, etc.  These classes are in the puppetlabs\\_spec\n   directory.\n3. To provide a common set of Rake tasks so that the procedure for testing modules\n   is unified.\n\nTo Use this Project\n===================\n\nThe most common usage scenario is that you will check out the 'main'\nbranch of this project from github, and install it as a rubygem.\nThere should be few or no cases where you would want to have any other\nbranch of this project besides main/HEAD.\n\nRunning on non-current ruby versions\n------------------------------------\n\nSince gem and bundler, ruby's package management tools, do not take the target ruby version into account when downloading packages, the puppetlabs_spec_helper gem can only depend on gems that are available for all supported ruby versions. If you can/want to use features from other packages, install those additional packages manually, or have a look at the Gemfile, which provides code to specify those dependencies in a more \"friendly\" way. This currently affects the following gems:\n\n* puppet\n* rubocop\n* rubocop-rspec\n* json_pure\n* rack\n\nInitializing Puppet for Testing\n===============================\n\nIn most cases, your project should be able to define a spec\\_helper.rb that includes\njust this one simple line:\n\n    require 'puppetlabs_spec_helper/puppet_spec_helper'\n\nThen, as long as the gem is installed, you should be all set.\n\nIf you are using rspec-puppet for module testing, you will want to include a different\nlibrary:\n\n    require 'puppetlabs_spec_helper/module_spec_helper'\n\nNOTE that this is specifically for initializing Puppet's core.  If your project does\nnot have any dependencies on puppet and you just want to use the utility classes,\nsee the next section.\n\nA number of the Puppet parser features, controlled via configuration during a\nnormal puppet run, can be controlled by exporting specific environment\nvariables for the spec run. These are:\n\n* ``STRICT_VARIABLES`` - Set to \"no\" to disable strict variable checking.\n  See [strict_variables](http://docs.puppetlabs.com/references/latest/configuration.html#strictvariables) in puppet.conf for details.\n* ``ORDERING`` - set to the desired ordering method (\"title-hash\", \"manifest\", or \"random\")\n  to set the order of unrelated resources when applying a catalog. Leave unset for the default\n  behavior, currently \"random\". This is equivalent to setting [ordering](http://docs.puppetlabs.com/references/latest/configuration.html#ordering)\n  in puppet.conf.\n\n  As an example, to run spec tests with the future parser, strict variable checking,\nand manifest ordering, you would:\n\n    ORDERING=manifest rake spec\n\n\nUsing Utility Classes\n=====================\nIf you'd like to use the Utility classes (PuppetlabsSpec::Files,\nPuppetlabsSpec::Fixtures), you just need to add this to your project's spec\\_helper.rb:\n\n    require 'puppetlabs_spec_helper/puppetlabs_spec_helper'\n\nNOTE that the above line happens automatically if you've required\n'puppetlabs\\_spec\\_helper/puppet\\_spec\\_helper', so you don't need to do both.\n\nIn either case, you'll have all of the functionality of Puppetlabs::Files,\nPuppetlabs::Fixtures, etc., mixed-in to your rspec context.\n\nUsing Fixtures\n==============\n`puppetlabs_spec_helper` has the ability to populate the\n`spec/fixtures/modules` directory with dependent modules when `rake spec` or\n`rake spec_prep` is run. To do so, all required modules should be listed in a\nfile named `.fixtures.yml` in the root of the project. You can specify a alternate location for that file in the `FIXTURES_YML` environment variable.\n\nYou can use the `MODULE_WORKING_DIR` environment variable to specify a diffent location when installing module fixtures via the forge. By default the\nworking directory is `\u003cmodule directory\u003e/spec/fixtures/work-dir`.\n\nWhen specifying the repo source of the fixture you have a few options as to which revision of the codebase you wish to use, and optionally, the puppet versions where the fixture is needed.\n\n * `repo` - the url to the repo\n * `scm` - options include git or hg. This is an optional step as the helper code will figure out which scm is used.\n\n   ```yaml\n   scm: git\n   scm: hg\n   ```\n\n * `target` - the directory name to clone the repo into ie. `target: mymodule`  defaults to the repo name  (Optional)\n * `subdir` - directory to be removed from the cloned repo. Its contents will be moved to the root directory (Optional)\n * `ref` - used to specify the tag name (like version) or commit hash to be checked out (Optional). Branch names should use the `branch` option instead.\n\n   ```yaml\n   ref: 1.0.0\n   ref: 880fca52c\n   ```\n * `branch` - used to specify the branch name you want to use ie. `branch: development`\n * `flags` - additional flags passed to the module installer (both puppet and scm)\n\n   ```yaml\n   flags: --verbose\n   ```\n * `puppet_version` - versions of puppet for which the fixture should be installed. Ruby version constraints are supported. Only works when the `semantic_puppet` gem is available (shipped with puppet 4.0 and up, by default).\n\n   ```yaml\n   puppet_version: '\u003e= 6.0.0'\n   ```\n\n **Notes:**\n\n * `ref` and `branch` can be used together to get a specific revision on a specific branch\n * Top level `defaults` option could be used to set global options\n\nUsing Forge Authorization\n-----------------\n\nIn order to perform forge operations which require authorization, such as installing premium modules, you can export your forge api key as an environment variable in your terminal.\n\n```bash\nFORGE_API_KEY='your_api_key'\n```\n\npuppetlabs_spec_helper will then automatically append this key to all `puppet module install` requests when running `rake spec_prep`.\n\nFixtures Examples\n-----------------\nBasic fixtures that will symlink `spec/fixtures/modules/my_modules` to the\nproject root:\n\n```yaml\nfixtures:\n  symlinks:\n    my_module: \"#{source_dir}\"\n```\n\nThis is the same as specifying no symlinks fixtures at all.\n\nAdd `firewall` and `stdlib` as required module fixtures:\n\n```yaml\nfixtures:\n  repositories:\n    firewall: \"https://github.com/puppetlabs/puppetlabs-firewall.git\"\n    stdlib: \"https://github.com/puppetlabs/puppetlabs-stdlib.git\"\n```\n\nPut a supplementary repository at a different location\n\n```yaml\nfixtures:\n  repositories:\n    firewall: \"https://github.com/puppetlabs/puppetlabs-firewall.git\"\n    stdlib: \"https://github.com/puppetlabs/puppetlabs-stdlib.git\"\n    control_repo:\n      repo: \"https://github.com/puppetlabs/control-repo\"\n      target: \"spec/fixtures/control_repos\"\n```\n\nSpecify that the git tag `2.4.2` of `stdlib` should be checked out:\n\n```yaml\nfixtures:\n  repositories:\n    firewall: \"https://github.com/puppetlabs/puppetlabs-firewall.git\"\n    stdlib:\n      repo: \"https://github.com/puppetlabs/puppetlabs-stdlib.git\"\n      ref: \"2.6.0\"\n```\n\nOnly install the `yumrepo_core` module when testing against Puppet 7 or greater:\n\n```yaml\nfixtures:\n  repositories:\n    yumrepo_core:\n      repo: \"https://github.com/puppetlabs/puppetlabs-yumrepo_core.git\"\n      puppet_version: \"\u003e= 6.0.0\"\n```\n\nMove manifests and siblings to root directory when they are inside a `code` directory:\n\n```yaml\nfixtures:\n  repositories:\n    stdlib:\n      repo: \"https://github.com/puppetlabs/puppetlabs-extradirectory.git\"\n      subdir: \"code\"\n```\n\nInstall modules from Puppet Forge:\n\n```yaml\nfixtures:\n  forge_modules:\n    firewall: \"puppetlabs/firewall\"\n    stdlib:\n      repo: \"puppetlabs/stdlib\"\n      ref: \"2.6.0\"\n```\n\nPass additional flags to module installation:\n\n```yaml\nfixtures:\n  forge_modules:\n    stdlib:\n      repo: \"puppetlabs/stdlib\"\n      ref: \"2.6.0\"\n      flags: \"--module_repository https://my_repo.com\"\n    repositories:\n      firewall:\n        repo: \"https://github.com/puppetlabs/puppetlabs-firewall.git\"\n        ref: \"2.6.0\"\n        flags: \"--verbose\"\n```\n\nUse `defaults` to define global parameters:\n\n```yaml\ndefaults:\n  forge_modules:\n    flags: \"--module_repository https://my_repo.com\"\nfixtures:\n  forge_modules:\n    stdlib:\n      repo: \"puppetlabs/stdlib\"\n      ref: \"2.6.0\"\n    repositories:\n      firewall:\n        repo: \"https://github.com/puppetlabs/puppetlabs-firewall.git\"\n        ref: \"2.6.0\"\n```\n\nFixture Loading\n---------------\nAny module that has a `spec/lib` directory will be available on the ruby `LOAD_PATH` for tests to consume. This allows modules to provide additional helper code to be supplied. The [augeasprovider_core](https://github.com/hercules-team/augeasproviders_core) module has [some examples](https://github.com/hercules-team/augeasproviders_core/tree/master/spec/lib).\n\nTesting Parser Functions\n========================\n\nThis whole section is superseded by improved support of accessing the scope in\nrspec-puppet.\n\n\nModify rspec behavior\n================================\n\n#### Running Rspec with additional settings\n\nYou can add command line options to rspec using the `CI_SPEC_OPTIONS` environment variable.  Any text in the `CI_SPEC_OPTIONS` environment variable is added as an rspec option.  For example:\n\nIf you wanted to output JUnit test reports for a Jenkins CI server you could use;\n\nBash\n``` bash\nexport CI_SPEC_OPTIONS = \"-r yarjuf -f JUnit -o result.xml\"\n```\n\nPowerShell\n``` bash\n$ENV:CI_SPEC_OPTIONS = '-r yarjuf -f JUnit -o result.xml'\n```\n\nAnd then run\n```\nbundle exec rake spec\n```\n\nThis would cause rspec to load the `yarjuf` gem and output the results in JUnit format to the file `result.xml`\n\n#### Running specs in parallel\nWhen executing tests in a matrix CI environment, tests can be split up to run\na share of specs per CI node in parallel.  Set the ``CI_NODE_TOTAL`` environment\nvariable to the total number of nodes, and the ``CI_NODE_INDEX`` to a number\nbetween 1 and the ``CI_NODE_TOTAL``.\n\nIf using Travis CI, add new lines to the \"env\" section of .travis.yml per node,\nremembering to duplicate any existing environment variables:\n\n    env:\n      - FUTURE_PARSER=yes CI_NODE_TOTAL=2 CI_NODE_INDEX=1\n      - FUTURE_PARSER=yes CI_NODE_TOTAL=2 CI_NODE_INDEX=2\n\n#### Running tests tagged with test tiers\nTo run tests tagged with risk levels set the ``TEST_TIERS`` environment variable to a comma-separated list of the appropriate tiers.\n\nFor example: to run tests marked ``tier_high =\u003e true`` and ``tier_medium =\u003e true`` in the same test run set the\nenvironment variable``TEST_TIERS=high,medium``\n\nBy default ``TEST_TIERS`` only accepts low, medium and high as valid tiers.  If you would like to use your own keywords to set the environment variable ``TEST_TIERS_ALLOWED``.\n\nFor example: to use the keywords dev, rnd, staging and production you can set\n``TEST_TIERS_ALLOWED=dev,rnd,staging,production``. Then you would be able to run tests marked ``tier_dev =\u003e true``, ``tier_production =\u003e true`` with ``TEST_TIERS=dev,production``\n\nNote, if the ``TEST_TIERS`` environment variable is set to empty string or nil, all tiers will be executed.\n\n\nGenerating code coverage reports\n================================\n\nThis section describes how to add code coverage reports for Ruby files (types, providers, ...).\nSee the documentation of [RSpec-Puppet](https://github.com/rodjek/rspec-puppet)\nfor Puppet manifest coverage reports.\n\nStarting with Ruby 1.9, the *de facto* standard for Ruby code coverage is\n[SimpleCov](https://github.com/colszowka/simplecov). It is implemented as a Rake task in this gem.\n\nTo run code coverage:\n\n    $ rake spec:simplecov\n\nReports are written to `/coverage/`, which you should add to `.gitignore`.\n\nThe reports can be generated every time you invoke RSpec, e.g. via `rake spec`,\nYou can enable it, set the following environment variable:s\n\n``SIMPLECOV=yes``\n\nRemember to add the simplecov-console gem to your `Gemfile`. If you run `spec:simplecov` on Travis-CI or any of the other supported CI services, reports get generated which can then be uploaded to [codecov.io](https://codecov.io) with the recommended [codecov uploader](https://docs.codecov.com/docs/codecov-uploader).\n\nSome Notes for Windows Users\n============================\n\nA windows users may need to do one of two things to execute `rake spec`.\n\nAlthough things may appear to work, the init.pp may not transfer to the fixtures folder as needed\nor may transfer as an empty file.\n\nThis is related to a registry security setting requiring elevated privileges to create symbolic links.\n\nCurrently, there are two known approaches to get around this problem.\n\n- run your windows shell (cmd) as an Administrator\nor\n- modify the registry entry settings to allow symbolic links to be created.\n\nThe following links may give you some insight into why...\n\n[Server Fault Post](http://serverfault.com/questions/582944/puppet-file-link-doesnt-create-target-under-windows)\n\n[Stack Overflow Post](http://stackoverflow.com/questions/229643/how-do-i-overcome-the-the-symbolic-link-cannot-be-followed-because-its-type-is)\n\n[Microsoft TechNet](https://technet.microsoft.com/en-us/library/cc754077.aspx)\n\nmock_with\n=========\n\nThere are two major mocking frameworks in modules test suites today: [mocha](https://rubygems.org/gems/mocha) and [rspec-mocks](https://rubygems.org/gems/rspec-mocks). We recommend that you choose rspec-mocks explicitly by specifying `mock_with`, either in your `spec_helper.rb` like so:\n\n```\nRSpec.configure do |c|\n  c.mock_with :rspec\nend\nrequire 'puppetlabs_spec_helper/module_spec_helper'\n```\n\nor by using Puppet Development Kit's [`mock_with` option in `.sync.yml`](https://github.com/puppetlabs/pdk-templates#specspec_helperrb) and `pdk update`.\n\nYou can also continue to use mocha by explicitly specifying `:mocha`, following the [mocha documentation](http://gofreerange.com/mocha/docs/).\n\nMigration\n---------\n\nTo migrate from mocha to rspec-mocks, in many simple cases the following two kinds of changes are all you need:\n\nTranslate all stubs:\n```\ncontext.stubs(:some_method).with(arguments).returns('value')\n```\nto this:\n```\nallow(context).to receive(:some_method).with(arguments).and_return('value')\n```\n\nTranslate all expectations:\n```\ncontext.expects(:some_method).with(arguments).returns('value')\n```\nto this:\n```\nexpect(context).to receive(:some_method).with(arguments).and_return('value')\n```\n\nRationale\n---------\n\n* As a part of the RSpec project, rspec-mocks integration is better.\n* mocha is extending base ruby objects with its `stubs`, and `expects` methods, polluting the global namespace, with a potential for subtle and gnarly errors.\n* Currently both rspec-mocks and mocha get loaded, leading to test suites that use both.\n* puppetlabs_spec_helper loads and configures mocha unconditionally, causing friction when a different mocking framework is wanted.\n* mocha is an additional dependency to carry.\n\nEOF\n\n## License\n\nThis codebase is licensed under Apache 2.0. However, the open source dependencies included in this codebase might be subject to other software licenses such as AGPL, GPL2.0, and MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs_spec_helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs_spec_helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs_spec_helper/lists"}