= RSpec::PGPMatchers

image:https://img.shields.io/gem/v/rspec-pgp_matchers.svg[
	Gem Version, link="https://rubygems.org/gems/rspec-pgp_matchers"]
image:https://img.shields.io/travis/riboseinc/rspec-pgp_matchers/master.svg[
	Build Status, link="https://travis-ci.org/riboseinc/rspec-pgp_matchers/branches"]
image:https://img.shields.io/codecov/c/github/riboseinc/rspec-pgp_matchers.svg[
	Test Coverage, link="https://codecov.io/gh/riboseinc/rspec-pgp_matchers"]
image:https://img.shields.io/codeclimate/maintainability/riboseinc/rspec-pgp_matchers.svg[
	"Code Climate", link="https://codeclimate.com/github/riboseinc/rspec-pgp_matchers"]

RSpec matchers for testing PGP-encrypted messages, and signatures.

CAUTION: This gem is not meant to bridge GnuPG executables to production
environments.  Use it in developments and tests only.

IMPORTANT: This gem calls GnuPG executables internally.  However, it does not
rely on machine-readable interface yet, and may easily break when they change
something in GnuPG's human-readable output. As long as it is not resolved in
a better way, we are going to maintain compatibility with the most recent
versions of GnuPG.  At the moment of writing this statement, it is GnuPG 2.2.9.

TIP: In order to check which GnuPG version this gem was tested against,
check out builds in Travis.  One of the build steps in a "before script" phase
executes `gpg --version` to make things clear.

== Usage

=== Getting started

1. Make sure that you have GnuPG 2.2 installed.

2. Add this line to your application’s Gemfile:
+
[source,ruby]
----
gem "rspec-pgp_matchers", github: "riboseinc/rspec-pgp_matchers", require: false, group: :test
----

3. And following to your spec helper:
+
[source,ruby]
----
require "rspec/pgp_matchers"
RSpec::PGPMatchers.homedir = "path/to/pgp_home_directory/with/development/keys"
----

=== Matching signatures

[source,ruby]
----
text = "Some text"
signer_uid = "mail@example.com"
someones_uid = "someone@example.com"

# Not defined in this gem, but required for this example
signature = sign_text(text: text, signer: signer_uid, ascii_armor: true)

# Both following do pass
expect(signature).to be_a_valid_pgp_signature_of(text)
expect(signature).to be_a_valid_pgp_signature_of(text).signed_by(signer_uid)

# This one fails
expect(signature).to be_a_valid_pgp_signature_of(text).signed_by(someones_uid)
----

=== Matching encrypted messages

[source,ruby]
----
text = "Some text"
recipient1_uid = "mail1@example.com"
recipient2_uid = "mail2@example.com"
someones_uid = "someone@example.com"

# Not defined in this gem, but required for this example
encrypted = encrypt_text(
  text: text,
  recipients: [recipient1_uid, recipient2_uid],
  ascii_armor: true
)

# Following do pass
expect(encrypted).to be_a_pgp_encrypted_message
expect(encrypted).to be_a_pgp_encrypted_message.containing(text)
expect(encrypted).to be_a_pgp_encrypted_message.encrypted_for(recipient1_uid, recipient2_uid)

# This one fails
expect(encrypted).to be_a_pgp_encrypted_message.encrypted_for(someones_uid)
----

=== Running arbitrary GnuPG commands

An `RSpec::PGPMatchers::GPGRunner` module can be used to run arbitrary GnuPG
commands:

[source,ruby]
----
RSpec::PGPMatchers::GPGRunner.run_command("--decrypt PATH_TO_FILE")
RSpec::PGPMatchers::GPGRunner.run_command("--list-keys")
----

Also, convenient helpers are defined for two common commands:

[source,ruby]
----
RSpec::PGPMatchers::GPGRunner.run_decrypt("encrypted_string")
RSpec::PGPMatchers::GPGRunner.run_verify("cleartext", "signature_string")
----

In all above cases, a triple consisting of captured standard output, captured
standard error, and `Process::Status` instance is returned.

== Development

After checking out the repo, run `bin/setup` to install dependencies.
Then, run `rake spec` to run the tests. You can also run `bin/console`
for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run
`bundle exec rake install`. To release a new version, update the version
number in `version.rb`, and then run `bundle exec rake release`, which
will create a git tag for the version, push git commits and tags, and
push the `.gem` file to https://rubygems.org[rubygems.org].

== Contributing

Bug reports and pull requests are welcome on GitHub at
https://github.com/riboseinc/rspec-pgp_matchers.

== Credits

This gem is developed, maintained and funded by
https://www.ribose.com[Ribose Inc].

== License

The gem is available as open source under the terms of the
https://opensource.org/licenses/MIT[MIT License].