diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d999ee387..e7bd28b6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,35 @@ # Contributing -Post to [puppet-users@groups.google.com](https://groups.google.com/forum/#!forum/puppet-users) for questions. Error reports and patches welcome in this repo! +We welcome error reports and patches to the PDK repository. Post questions to [puppet-users@groups.google.com](https://groups.google.com/forum/#!forum/puppet-users). Post bug reports and pull requests on GitHub at https://github.com/puppetlabs/pdk/issues. # Running from source -In cases where `pdk` needs to run in a working directory outside the cloned repository, either set `BUNDLE_GEMFILE` to the pdk's Gemfile location, or install and use the [binstubs of bundler](http://bundler.io/v1.15/bundle_binstubs.html), which are small proxy binaries, that set up the environment for running the tool. +If you need to run `pdk` in a working directory outside the cloned repository, either set `BUNDLE_GEMFILE` to the pdk's Gemfile location, or install and use the [binstubs of bundler](http://bundler.io/v1.15/bundle_binstubs.html). These binstubs are small proxy binaries that set up the environment for running the tool. ``` # assuming ~/bin is already on your path: $ bundle binstubs pdk --path ~/bin ``` -Bug reports and pull requests are welcome on GitHub at https://github.com/puppetlabs/pdk/issues. - # Running tests -pdk has the following testing rake tasks +pdk has the following testing Rake tasks. ## spec -Run unit tests. +Runs unit tests. ## rubocop -Run ruby style checks. Use `rake rubocop:auto_correct` to fix the easy ones. +Runs Ruby style checks. Use `rake rubocop:auto_correct` to fix the easy ones. ## acceptance:local -Run acceptance tests on the current pdk code. These tests are executed on commits and pull requests to this repo using both travis and appveyor. +Runs acceptance tests on the current pdk code. These tests are executed on commits and pull requests to this repo using both travis and appveyor. # Testing packages -The package-testing/ folder contains files for testing built packages of pdk. This is for Puppet's packaging CI, and contributors outside of Puppet, Inc. don't need to worry about executing it. It uses [beaker](https://github.com/puppetlabs/beaker) to provision a VM, fetch and install a pdk installation package, and then run the acceptance tests on that VM. +The package-testing/ folder contains files for testing built packages of pdk. This is for Puppet's packaging CI, so contributors outside of Puppet, Inc. don't need to worry about executing it. It uses [beaker](https://github.com/puppetlabs/beaker) to provision a VM, fetch and install a pdk installation package, and then run the acceptance tests on that VM. This folder has its own Gemfile and Rakefile providing an _acceptance_ rake task. It requires some environment variables to be set in order to specify what beaker will set up: diff --git a/README.md b/README.md index 978066c5e..80d54f59c 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,41 @@ # pdk [![Build Status](https://travis-ci.org/puppetlabs/pdk.svg?branch=master)](https://travis-ci.org/puppetlabs/pdk) [![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/x70e2fqllbaootpd?svg=true)](https://ci.appveyor.com/project/puppetlabs/pdk) [![Coverage Status](https://coveralls.io/repos/github/puppetlabs/pdk/badge.svg?branch=master)](https://coveralls.io/github/puppetlabs/pdk?branch=master) +* [Installation](#installation) +* [Basic usage](#basic-usage) +* [Experimental features](#experimental-features) +* [Module compatibility](#module-compatibility) +* [Contributing](#contributing) -A CLI to facilitate easy, unified development workflows for Puppet modules. `pdk` is a key part of the Puppet Development Kit, the shortest path to better modules. +The Puppet Development Kit (PDK) includes key Puppet code development and testing tools for Linux, Windows, and OS X workstations, so you can install one package with the tools you need to create and validate new modules. -## Installation - -Download and install the newest package matching your platform from [here](https://drive.google.com/drive/folders/0Bz0tCHSb1u41alR4MmZfRHBTV1k?usp=sharing). If you are using Windows, please remember to close any open PowerShell windows. - -### Windows - -On Windows you should run PDK from PowerShell and `pdk` will be available in your PowerShell prompt after installation. +PDK includes testing tools, a complete module skeleton, and command line tools to help you create, validate, and run tests on Puppet modules. PDK also includes all dependencies needed for its use. -If the `pdk` command does not appear, check that the `PuppetDevelopmentKit` PowerShell module is loaded in your PowerShell prompt: +PDK includes the following tools: -``` -Get-Module -Name PuppetDevelopmentKit -``` +Tool | Description +----------------|------------------------- +metadata-json-lint | Validates and lints `metadata.json` files in modules against Puppet's module metadatastyle guidelines. +pdk | Command line tool for generating and testing modules +puppet-lint | Checks your Puppet code against the recommendations in the Puppet Language style guide. +puppet-syntax | Checks for correct syntax in Puppet manifests, templates, and Hiera YAML. +puppetlabs_spec_helper | Provides classes, methods, and Rake tasks to help with spec testing Puppet code. +rspec-puppet | Tests the behavior of Puppet when it compiles your manifests into a catalog of Puppet resources. +rspec-puppet-facts | Adds support for running rspec-puppet tests against the facts for your supported operating systems. -If no output is returned, load the `PuppetDevelopmentKit` module by running the following command: - -``` -Import-Module -Name PuppetDevelopmentKit -``` - -> Note: On PowerShell version 3 and above, PowerShell modules are loaded automatically so this step shouldn't be necessary. - -You should set your script execution policy to at least [RemoteSigned](https://msdn.microsoft.com/en-us/powershell/reference/5.1/microsoft.powershell.security/set-executionpolicy), if it's not already, to allow the PowerShell integration to work. - -You can check your ExecutionPolicy by running the following command from a PowerShell prompt: - -``` -Get-ExecutionPolicy -``` -To set the `ExecutionPolicy`, run the following command: +## Installation -``` -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -``` +Download and install the newest package matching your platform from the [download](https://puppet.com/download-puppet-development-kit) page. If you are using Windows, remember to close any open PowerShell windows. -If you can't change the system `ExecutionPolicy`, you can change the `ExecutionPolicy` for just the current session by using the `Scope` paramter: +For complete installation information, see the [PDK documentation](https://docs.puppet.com/pdk/latest/pdk_install.html). -``` -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -``` - -For more information about PowerShell `ExecutionPolicies` or how to change them, see [about_Execution_Policies](http://go.microsoft.com/fwlink/?LinkID=135170). +## Basic usage -## Usage +PDK can generate modules and classes, validate module metadata, style, and syntax, and run unit tests. This README contains very basic usage information---for complete usage information, see the [PDK documentation](https://docs.puppet.com/pdk/). -### Generate a new module +### Generate a module -To get started, generate a new module from the default template. +Generates the basic components of a module and set up an infrastructure for testing it with PDK. 1. Run the `pdk new module` command, specifying the name of the new module: @@ -59,241 +43,49 @@ To get started, generate a new module from the default template. pdk new module my_module ``` -This generates the basic components of a new module. The `pdk new module` command sets some default metadata values based on your environment. Check the `metadata.json` to make sure that these values are correct. The new module now contains all the infrastructure to use the other capabilities of `pdk`. - -### Running validations +This command asks a series of metadata questions and then generates the basic components of a new module. -The default template provides tools for running static validations of your new module. Validations run quickly, but they provide only a basic check of the well-formedness of the module and syntax of its files. +### Generate a class -``` -pdk validate -``` - -This displays results in the console: +To generate a class in your module, use the `pdk new class` command, specifying the name of your new class. To generate the main class of the module, which is defined in an `init.pp` file, give the class the same name as the module. -``` -pdk (INFO): Running all available validators... -[✔] Checking for missing Gemfile dependencies -[✔] Checking metadata.json -[✔] Checking Ruby code style -[...] -``` +1. From the command line, in your module's directory, run `pdk new class class_name`. + ``` -Specific validators can be run by providing the validator name (or a comma -separated list of names) as an argument to `pdk validate`. +PDK creates the new class manifest and a test file (as `class_name_spec.rb`) in your module's `/spec/classes` directory. -``` -$ pdk validate metadata -[✔] Checking for missing Gemfile dependencies -[✔] Checking metadata.json -``` -By default each validator will automatically determine which files in the -module that it should validate, however validations can be run on specific -files or directories by providing them as arguments to `pdk validate` +### Validating a module -``` -$ pdk validate lib/ -[✔] Checking for missing Gemfile dependencies -[✔] Checking Ruby code style -``` +PDK can validate the well-formedness of the module and style and syntax of its files. -Some validators support automatic correction of detected problems (for example, -both rubocop and puppet-lint can automatically correct many common code style -problems). To enable this functionality, run `pdk validate` with the -`--auto-correct` option. +1. In the module's directory, run: ``` -$ pdk validate --auto-correct -pdk (INFO): Running all available validators... -[✔] Checking for missing Gemfile dependencies -[✔] Checking metadata.json -[✔] Checking Puppet manifest style -[✔] Checking Puppet manifest syntax -[✔] Checking Ruby code style -manifests/init.pp:1:10: corrected: double quoted string containing no variables +pdk validate ``` -#### Run in parallel - -Module validation can also be run in parallel and supports the same selectors for -validators, files, and directories as non-parallel validation. - -``` -$ pdk validate --parallel -pdk (INFO): Running all available validators... -┌ [✔] Validating module using 3 threads -├──[✔] Checking metadata syntax (metadata.json) -├──[✔] Checking Puppet manifest syntax -├──[✔] Checking Ruby code style -├──[✔] Checking metadata style (metadata.json) -└──[✔] Checking Puppet manifest style -``` +This command validates the metadata, Puppet code syntax and style, and Ruby syntax and style for the entire module. ### Run unit tests -The default template sets up [rspec](http://rspec.info/) for Ruby-level unit testing, and [rspec-puppet](https://github.com/rodjek/rspec-puppet/) for catalog-level unit testing. +PDK's default template sets up [rspec](http://rspec.info/) for Ruby-level unit testing, and [rspec-puppet](https://github.com/rodjek/rspec-puppet/) for catalog-level unit testing. -1. In the module's directory, run all unit tests with: +In the module's directory, run unit tests with: ``` pdk test unit ``` - - - -## Reference - -### `pdk new module` command - -Generates a new module. - -Usage: - -``` -pdk new module [--template-url=git_url] [--license=spdx_identifier] module_name [target_dir] -``` - -The `pdk new module` command accepts the following arguments and options. Arguments are optional unless otherwise specified. - -#### `--template-url=git_url` - -Overrides the template to use for this module. If possible, please contribute your improvements back to the default template at [puppetlabs/pdk-module-template](https://github.com/puppetlabs/pdk-module-template). - -#### `--license=spdx_identifier` - -Specifies the license this module is written under. See https://spdx.org/licenses/ for a list of open source licenses, or use `proprietary`. Defaults to `Apache-2.0`. - -#### `--skip-interview` - -Suppress interactive queries for initial values. All questions will use the default values. - -#### `module_name` - -**Required**. Specifies the name of the module being created. e.g.: `my_module` - -#### `target_dir` - -Specifies the directory that the new module will be created in. Defaults to creating a new directory with the given `module_name` inside the current directory. - -### `pdk new class` command - -Generates a new class and skeleton test for it in the current module. - -Usage: - -``` -pdk new class [--template-url=git_url] -``` - -e.g. - -``` -cd my_module -pdk new class my_class -``` - -#### `--template-url` - -Overrides the template to use when generating this class. If this is not -specified, the template used to generate the module will be used instead. If -that template is not available, the default template at -[puppetlabs/pdk-module-template](https://github.com/puppetlabs/pdk-module-template) -will be used. - -#### `class_name` - -The name of the class to generate. If the class name is not inside the module -namespace (e.g. module name is `apt` and the class name is `source`, then the -module name will automatically be prepended to the class name (e.g. -`apt::source`). - -### `pdk validate` command - -Runs all static validations. Any errors are reported to the console in the format requested. The exit code is non-zero when errors occur. - -Usage: - -``` -pdk validate --list -``` - -``` -pdk validate [--format=format[:target]] [validations] [targets*] -``` - -#### `--list` - -Displays a list of available validations and their descriptions. Using this option lists the tests without running them. - -#### `--format=format[:target]` - -Specifies the format of the output. Valid values: `junit`, `text`. Default: `text`. - -Optionally, you can specify a target file for the given output format with the syntax: `--format=junit:report.xml` - -Multiple `--format` options can be specified as long as they all have distinct output targets. - -#### `validations` - -Specifies a comma separated list of validations to run (or `all`). See the `--list` output for a list of available validations. Defaults to `all` if not supplied. - -#### `targets` - -Specifies a list of directories or individual files to validate. Validations which are not applicable to individual files will be skipped for those files. Defaults to validating everything. - -#### Additional Examples - -``` -$ pdk validate metadata -Running 'metadata' validation on `new_module`: OK! -``` - -``` -$ pdk validate all lib/ -Running validations on `new_module/lib`: -* ruby syntax: OK! -* puppet syntax: (no puppet manifests found) -``` - -### `pdk test unit` command - -Runs unit tests. Any errors are displayed to the console and reported in the report-file, if requested. The exitcode is non-zero when errors occur. +This command runs all available unit tests. -Usage: - -``` -pdk test unit [--list] [--tests=test_list] [--format=format[:target]] [runner_options] -``` - -#### `--list` - -Displays a list of unit tests and their descriptions. Using this option lists the tests without running them. - -#### `--tests=test_list` - -A comma-separated list of tests to run. Use this during development to pinpoint a single failing test. See the `--list` output for allowed values. - -#### `--format=format[:target]` - -Specifies the format of the output. Valid values: `junit`, `text`. Default: `text`. - -Optionally, you can specify a target file for the given output format with the syntax: `--format=junit:report.xml` - -Multiple `--format` options can be specified as long as they all have distinct output targets. - -#### `runner_options` - - - -Specifies options to pass through to the actual test-runner. In the default template (and most commonly across modules), this is [rspec](https://relishapp.com/rspec/rspec-core/docs/command-line). +## Experimental features ### `pdk bundle` command -This experimental command allows advanced users to execute arbitrary commands in a bundler context within the module you're currently working on. Arguments to this command are passed straight through to bundler. Careless use of this command can lead to errors later which can't be recovered by the pdk itself. +This command executes arbitrary commands in a bundler context within the module you're currently working on. Arguments to this command are passed straight through to bundler. This command is experimental and can lead to errors that can't be resolved by the pdk itself. -Note that for most advanced uses it is required to use the `--` to separate bundler options from pdk options. Compare the following two commands: +Note that for most uses, you must use the `--` to separate bundler options from pdk options. Compare the following two commands: ``` $ pdk bundle exec rake -T @@ -312,21 +104,20 @@ rake build # Build puppet module package [...] ``` -## Module Compatibility +#### Known issues + +* `pdk bundle` command on Windows doesn't allow usage suggested by pdk help [PDK-408](https://tickets.puppetlabs.com/browse/PDK-408) -**PDK Version Compatibility:** modules created with a specific PDK version should validate against and run on all Puppet andRuby version combinations currently under maintenance (see https://docs.puppet.com/puppet/latest/about_agent.html and https://puppet.com/misc/puppet-enterprise-lifecycle) +On Windows, the `pdk bundle` command doesn't allow `--` as a separator between pdk option flags and bundler option flags as suggested by `pdk help bundle`. -**Module Template Compatibility:** Modules created with a specific version of the PDK will remain compatible to newer versions of the PDK with the following exceptions: -* access to new PDK functionality might require an update of the module to the current Template version -* access to a new major PDK version might require an update of the module to the current Template version, after a one year deprecation cycle -* validation against new Puppet versions might require new PDK functionality, a new major PDK version, and changes to the module itself. +The issue is that PDK is consuming command line options meant for the subcommand. To work around this, run `pdk bundle exec` with a string specifying the command you want to run with its command line options. -## Upgrading -* In the common case, Puppet and the PDK will be forward-compatible so that minor Puppet updates will not require a new version of the PDK. -* Some new Puppet versions will require changes to the PDK. In that case, upgrading the PDK for validation prior to roll-out of Puppet is strongly recommended. +For example: `pdk bundle exec "bundle install --binstubs"` +## Module Compatibility +**PDK Version Compatibility:** Modules created with PDK version validate against and run on all Puppet and Ruby version combinations currently under maintenance (see https://docs.puppet.com/puppet/latest/about_agent.html and https://puppet.com/misc/puppet-enterprise-lifecycle) ## Contributing -See the [CONTRIBUTING.md](CONTRIBUTING.md) file for development notes. +PDK encourages community contributions. See the [CONTRIBUTING.md](CONTRIBUTING.md) file for development notes. diff --git a/docs/pdk.md b/docs/pdk.md deleted file mode 100644 index 408302326..000000000 --- a/docs/pdk.md +++ /dev/null @@ -1,35 +0,0 @@ - -**Note: this page is a draft in progress for a tech preview release and may differ from the final version.** - -## Puppet Development Kit - -The Puppet Development Kit (PDK) is a package of development and testing tools to help you create great Puppet modules. - -The PDK includes key Puppet code development and testing tools for Linux, Windows, and Mac OS X workstations, so you can install one package with the tools you need to create and validate new modules. PDK includes testing tools, a complete module skeleton, and command line tools to help you create, validate, and run tests on Puppet modules. PDK also includes all dependencies needed for its use. - -PDK includes the following tools: - -Tool | Description -----------------|------------------------- -pdk | Command line tool for generating and testing modules -rspec-puppet | Tests the behavior of Puppet when it compiles your manifests into a catalog of Puppet resources. -puppet-lint | Checks your Puppet code against the recommendations in the Puppet Language style guide. -puppet-syntax | Checks for correct syntax in Puppet manifests, templates, and Hiera YAML. -metadata-json-lint | Validates and lints `metadata.json` files in modules against Puppet's module metadatastyle guidelines. -rspec-puppet-facts | Adds support for running rspec-puppet tests against the facts for your supported operating systems. -puppetlabs_spec_helper | Provides classes, methods, and Rake tasks to help with spec testing Puppet code. - - -## Getting started - -To get started, install the PDK, and then create and test a module. - - - -1. [Generate a module](./pdk_generating_modules.md) using the `pdk new module` command. -1. [Validate your module](./pdk_testing.md#validating-modules), to verify that it is well-formed. -1. [Unit test](./pdk_testing.md#unit-testing-modules) your module, to verify that all dependencies and directories are present. -1. [Generate a class](./pdk_generating_modules.md#generate-a-new-class) for your module, using the `pdk new class` command. -1. Validate and unit test your module to verify that the new code was created correctly. - -PDK can unit test code that it generates, but for any other code you add, you'll need to write unit tests. As you add code to your module, be sure to validate and unit test your module both before and after adding code. This ensures that you are always developing on a clean, valid codebase. diff --git a/docs/pdk_generating_modules.md b/docs/pdk_generating_modules.md deleted file mode 100644 index f423f2ee4..000000000 --- a/docs/pdk_generating_modules.md +++ /dev/null @@ -1,84 +0,0 @@ - -**Note: this page is a draft in progress for a tech preview release and may differ from the final version.** - -## Generating modules and classes with PDK - -PDK generates the basic components of a module and sets up the basic infrastructure for testing it. - -When you create a module, PDK asks you a series of questions that it uses to create metadata for your module. - -Each question has a default response that PDK uses if you skip the question. The answers you provide to these questions are stored and used as the new defaults for subsequent module generations. Optionally, you can skip the interview step and use the default answers for all metadata. - -* Your Puppet Forge username. If you don't have a Forge account, you can accept the default value for this question. If you create a Forge account later, edit the module metadata manually with the correct value. -* Module version. We use and recommend semantic versioning for modules. -* The module author's name. -* The license under which your module is made available. This should be an identifier from [SPDX License List](https://spdx.org/licenses/). -* A one-sentence summary about your module. -* The URL to your module's source code repository, so that other users can contribute back to your module. -* The URL to a web site that offers full information about your module, if you have one.. -* The URL to the public bug tracker for your module, if you have one. - -After you generate a module, we suggest validating and testing the module _before_ you add classes or write new code in it. This allows you to verify that the module files and directories were correctly created. - -PDK does not generate any classes at module creation. The `pdk new class` command creates a class manifest and a test template file for the class. When you run this command, PDK creates a class manifest and a test template file for the class. You can then write tests in this template to validate your class's behavior. - -## Generate a module with pdk - -To generate a module with PDK's default template, use the `pdk new module` command. - -Before you begin, ensure that you've installed the PDK package. - -1. From the command line, run the `pdk new module` command, specifying the name of the module: `pdk new module module_name` - - Optionally, to skip the interview questions and generate the module with default values, use the `skip-interview` flag when you generate the module: `pdk new module module_name --skip-interview` - -1. Respond to the PDK dialog questions in the terminal. Each question indicates the default value it will use if you just hit **Enter**. - - 1. Forge username: Enter your Forge username, if you have a Forge account. - 2. Version: Enter the semantic version of your module, such as "0.1.0". - 3. Author: Enter the name of the module author. - 4. License: If you want to specify a license other than "Apache-2.0," specify that here, such as "MIT", or "proprietary". - 5. Description: Enter a one-sentence summary that helps other users understand what your module does. - 6. Source code repository: Enter the URL to your module's source code repository. - 7. Where others can learn more: If you have a website where users can learn more about your module, enter the URL. - 8. Where others can report issues: If you have a public bug tracker for your module, enter the URL. - -1. If the metadata that PDK displays is correct, confirm with `Y` or **Enter** to generate the module. If it is incorrect, enter `n` to cancel and start over. - -### Module contents - -PDK generates a basic module, a directory with a specific structure. This module contains directories and files you need to start developing and testing your module. - -To learn the basics of what a Puppet module includes, see the [Puppet docs on module fundamentals](https://docs.puppet.com/puppet/latest/modules_fundamentals.html). - -PDK creates the following files and directories for your module: - -Files and directories | Description -----------------|------------------------- -Module directory | Directory with the same name as the module. Contains all of the module's files and directories. -Gemfile | File describing Ruby gem dependencies. -Rakefile | File listing tasks and dependencies. -`appveyor.yml` | File containing configuration for Appveyor CI integration. -`metadata.json` | File containing metadata for the module. -`/manifests` | Directory containing module manifests, each of which defines one class or defined type. PDK creates manifests only when you generate them with the `pdk new class` command. -`/spec` | Directory containing files and directories for spec testing. -`/spec/spec_helper.rb` | File containing containing any ERB or EPP templates. -`/spec/default_facts.yaml` | File containing default facts. -`/spec/classes` | Directory containing testing templates for any classes you generate with the `pdk new class` command. -`/templates` | Directory containing any ERB or EPP templates. - -## Generate a new class - -To generate a new class in your module, use the `pdk new class` command, specifying the name of your new class. - -To generate the main class of the module, which is defined in an `init.pp` file, give the class the same name as the module. - -1. From the command line, in your module's directory, run `pdk new class class_name`. - - This example creates a new class named `class_name`. - - ``` bash - pdk new class class_name - ``` - -PDK creates the class in `module_name/manifests`. It also creates a test file (like `class_name_spec.rb`) in your module's `/spec/class` directory. This test file includes a basic template for writing your own unit tests. diff --git a/docs/pdk_reference.md b/docs/pdk_reference.md deleted file mode 100644 index 750ae3720..000000000 --- a/docs/pdk_reference.md +++ /dev/null @@ -1,85 +0,0 @@ - -**Note: this page is a draft in progress for a tech preview release and may differ from the final version.** - -## PDK reference - -### `pdk new module` command - -Generates a new module. - -Usage: - -``` -pdk new module [--template-url=git_url] [--license=spdx_identifier] module_name [target_dir] -``` - -The `pdk new module` command accepts the following arguments and options. Arguments are optional unless otherwise specified. - -Argument | Description | Values | Default -----------------|:---------------:|:------------------:|------------------------- -`--template-url=git_url` | Overrides the template to use for this module. | A valid Git URL. | No default. -`--license=spdx_identifier` | Specifies the license this module is written under. | See https://spdx.org/licenses/ for a list of open source licenses, or use `proprietary`. | Apache-2.0 -`--skip-interview` | Suppress interactive queries for initial values. Metadata will be generated with default values for all questions.| None | No default. -`module_name` | **Required**. Specifies the name of the module being created. | A module name beginning with a lowercase letter and including only lowercase letters, digits, and underscores. | No default. -`target_dir` | Specifies the directory that the new module will be created in. | A valid directory path | Creates a directory with the given `module_name` inside the current directory. - -### `pdk new class` command - -Generates a new class and test templates for it in the current module. - -Usage: - -``` -pdk new class [--template-url=git_url] -``` - -For example: - -``` -cd my_module -pdk new class my_class -``` - -Argument | Description | Values | Default -----------------|:---------------:|:------------------:|------------------------- -`--template-url` | Overrides the template to use when generating this class. | A valid URL to a class template. | Uses the template used to generate the module. If that template is not available, the default template at -[puppetlabs/pdk-module-template](https://github.com/puppetlabs/pdk-module-template) -is used. -`class_name` | **Required** The name of the class to generate. | A class name beginning with a lowercase letter and including only lowercase letters, digits, and underscores. | No default. - -### `pdk validate` command - -Runs all static validations. Any errors are reported to the console in the format requested. The exit code is non-zero when errors occur. - -Usage: - -``` -pdk validate --list -``` - -``` -pdk validate [--format=format[:target]] [validations] [targets*] -``` - -Argument | Description | Values | Default -----------------|:---------------:|:------------------:|------------------------- -`--list` | Displays a list of available validations and their descriptions. Using this option lists the tests without running them. | None. | No default. -`--format=format[:target]` | Specifies the format of the output. Optionally, you can specify a target file for the given output format with the syntax: `--format=junit:report.xml` Multiple `--format` options can be specified as long as they all have distinct output targets. | `junit` (JUnit XML), `text`(plain text) | `text` -`validations` | Specifies a comma-separated list of validations to run (or `all`) | See the `--list` output for a list of available validations. | `all` -`targets` | Specifies a list of directories or individual files to validate. Validations which are not applicable to individual files will be skipped for those files. | A space-separated list. | Validates all available directories and files. - -### `pdk test unit` command - -Runs unit tests. Any errors are displayed to the console and reported in the report-file, if requested. The exitcode is non-zero when errors occur. - -Usage: - -``` -pdk test unit [--list] [--tests=test_list] [--format=format[:target]] [runner_options] -``` - -Argument | Description | Values | Default -----------------|:---------------:|:------------------:|------------------------- -`--list` | Displays a list of unit tests and their descriptions. Using this option lists the tests without running them. | None. | No default. -`--tests=test_list` | A comma-separated list of tests to run. Use this during development to pinpoint a single failing test. | See the `--list` output for allowed values. | No default. -`--format=format[:target]` | Specifies the format of the output. Optionally, you can specify a target file for the given output format with the syntax:`--format=junit:report.xml`. Multiple `--format` options can be specified as long as they all have distinct output targets. | `junit` (JUnit XML), `text`(plain text). | `text` diff --git a/docs/pdk_testing.md b/docs/pdk_testing.md deleted file mode 100644 index 21241d3dd..000000000 --- a/docs/pdk_testing.md +++ /dev/null @@ -1,75 +0,0 @@ - -**Note: this page is a draft in progress for a tech preview release and may differ from the final version.** - -## Validating and testing your module with PDK - -The Puppet Development Kit (PDK) provides tools to help you run unit tests on your module and validate your module's metadata, syntax, and style. - -By default, the PDK module template includes tools that can: - -* Validate the `metadata.json`. -* Validate Puppet syntax. -* Validate Puppet code style. -* Validate Ruby code style. -* Run unit tests. - -### Validating modules - -The validations included in PDK provide a basic check of the well-formedness of the module and syntax and style of the module's files. You do not need to write any tests for this validation. - -By default, the `pdk validate` command validates the module's metadata, Puppet code syntax and style, and Ruby code syntax and style. You can also validates specific directories or files in the module, or validate only certain types of validation, such as metadata or Puppet code. - -You can also send module validation output in either JUnit or text format to a file. You can specify multiple output formats and targets in the same command, as long as the targets are each unique. - -### Validate a module - -To validate that your module is well-formed with correct syntax, run the `pdk validate` command. Optionally, you can validate only certain files or directories, run a specific type of validations, such as metadata or Puppet validation, or send your validation output to a file. - -1. In your module's directory, from the command line, run `pdk validate`. - - - * To run just one type of validation on the module, specify `puppet`, `ruby`, or `metadata`. For example, to validate the module's metadata, run `pdk validate metadata`. - - * To send module validation output to a file, use the `pdk validate` command with the option `--format=format[:target]`. This option specifies the output format and an output target file. For example, to create a report file `report.xml` in the JUnit format, run `pdk validate --format=junit:report.xml`. - - You can specify multiple `--format` options, as long as they all have distinct output targets. - - * To run validations on a specific directory or file, pass the name of the file or directory as an argument with `pdk validate`. For example, to run all validations on the `/lib` directory only, run `pdk validate lib/`. - -See the PDK reference for a complete list of validation options. - -### Unit testing modules - -PDK can also run your unit tests on a module's Puppet code to verify that the resources declared will be included in the catalog. PDK cannot test changes to the managed system or services. - -When you generate a class, PDK creates a unit test file. This test file, located in your module's `/spec/class` folder, includes a basic template for writing your unit tests. To learn more about how to write unit tests, see [rspec-puppet documentation](http://rspec-puppet.com/tutorial/). - -PDK includes tools for running unit tests, but it does not write unit tests itself. However, if you are testing an empty PDK-generated module, you can run the unit test command to ensure that all dependencies are present and that the spec directory was created correctly. - -After you've written your unit tests, you can use the `pdk test unit` command to run all of the tests you've included in your module. - -We suggest testing and validating your module anytime you are going to modify or add code, to verify that you are starting out with clean code. Then, as you create classes and write other code in your module, continue to write unit tests, validate, and unit test your code. - -Related links: - -* [rspec](http://rspec.info/) -* [rspec-puppet](https://github.com/rodjek/rspec-puppet/) -* [Writing rspec-puppet tests](http://rspec-puppet.com/tutorial/) - - -## Unit test your module - -To unit test your module, use the `pdk test unit` command. This command runs all the unit tests in your module. - -Before you begin, you need to have written unit tests for your module, unless you are unit testing a newly generated module with no classes or code in it. - -1. In your module's directory, from the command line, run: - -``` bash -pdk test unit -``` - -If there are no errors, this returns successfully (exit code 0) with no warnings or errors on 0 examples. - -See the PDK reference for a complete list of unit test options. -