rspec-graphql_response 0.1.0 → 0.4.1

data/UPGRADE.md

@@ -0,0 +1,41 @@
+# Upgrade Guide
+
+## v0.3.0 to v0.4.0
+
+There is a breaking change between v0.3.0 and v0.4.0 where the helper `graphql_query` was renamed to `graphql_operation`. In order to migrate to v0.4.0 all references to `graphql_query` can be replaced with `graphql_operation`.
+
+## v0.1.0 to v0.2.0
+
+There is a breaking change between v0.1.0 and v0.2.0 regarding the configuration of graphql queries, variables and context.
+Previously, you defined these three items with `let` in rspec:
+
+```ruby
+let(:graphql_query) { ... }
+```
+
+In v0.2.0, this changes to a new DSL for each of these three items:
+
+```ruby
+RSpec.describe My::Stuff, type: :graphql do
+
+  graphql_query <<-GQL
+    query Characters($name: String) {
+      characters(name: $name) {
+        id
+        name
+      }
+    }
+  GQL
+
+  graphql_variables({
+    name: "Jam"
+  })
+
+  graphql_context({
+    some: "context here",
+    current_user: some_user
+  })
+
+  it " ... "
+end
+```

data/docs/add_helper.md

@@ -0,0 +1,94 @@
+# Adding Helper Methods with `.add_helper`
+
+Much of the value that RSpec::GraphQLResponse brings is in the form of helper methods. Some helpers
+will let you simplify a spec from a verbose set of structure parsing, like this:
+
+```ruby
+it "does stuff" do
+  characters = response["data"]["characters"]
+
+  expect(characters).to include(
+    ...
+  )
+end
+```
+
+Down into something a little more reasonable with the `operation` helper, like this:
+
+```ruby
+it "does stuff" do
+  expect(operation(:characters)).to include(
+    ...
+  )
+end
+```
+
+It's not a huge difference, but when you consider how well the `operation` method handles `nil` and
+operation results that are not found, it's well worth the few lines of savings.
+
+There are many other helpers available for your test suites, as well. Be sure to check the full
+documentation list in the main readme.
+
+## Add a Spec Helper
+
+Most of the helpers that you'll want to add will be methods that are made available inside of
+your `it` (and related / similar) blocks, as shown above.
+
+To do this, you only need to call `RSpec::GraphQLResponse.add_helper(name, &helper_block)`. The `name` should
+be a symbol that represents the method name you wish to create. And the `&helper_block` is the actual
+method body, with any params you need.
+
+Within the helper body, you will have access to all available features of RSpec's `it` blocks, including
+other helper methods that come with RSpec::GraphQLResponse.
+
+A simple example can be found in the `operation` helper:
+
+```ruby
+RSpec::GraphQLResponse.add_helper :operation do |operation_name|
+  return nil unless response.is_a? Hash
+
+  response.dig("data", operation_name)
+end
+```
+
+In this example, the `response` helper is used, which guarantees the graphql has been executed and a response
+is available, assuming there were no exceptions preventing that.
+
+## Add a Context Helper
+
+In addition to Spec level helpers, RSpec::GraphQLResponse allows you to add custom helpers at the context
+level. This means you can add configuration and other bits that can be called outside of an `it` block.
+The existing `graphql_operation` and other DSL methods for configuring graphql calls are a great example of context level helpers.
+
+To create a context helper, call `RSpec::GraphQLResponse.add_context_helper(name, &helper_block)`. The params
+are the same as `.add_helper`, but the resulting method will be made available in `describe` and `context`
+blocks.
+
+```ruby
+RSpec::GraphQLResponse.add_context_helper :my_setting do |some_arg|
+  @my_setting = some_arg
+end
+```
+
+In this simple example, a method called `my_setting` is created, and it stores a value in the instance variable
+`@my_setting`. This takes advantage of RSpec's native ability to handle instance variables in describe and
+context blocks, allowing the variable to exist withing the hierarchy of objects for a given spec.
+
+With that defined, it can be used within a spec:
+
+```ruby
+RSpec.describe Cool::Thing, type: :graphql do
+
+  my_setting "this is a cool setting!"
+
+
+  it "has the setting" do
+    setting = self.class.instance_variable_get(:@my_setting)
+
+    expect(setting).to eq("this is a cool setting!")
+  end
+end
+```
+
+You may want to provide a better way of retrieving the `@my_setting` var from the class, but this at least
+demonstrates the ability to retrieve it from the class created by the `describe` block.

data/docs/add_validator.md

@@ -6,5 +6,172 @@ organizing your matcher code.
 
 To solve this, RSpec::GraphQLResponse introduced validators - code that is
 called to manage the validation of a graphql response, and provide the failure
-messages. Validators allow your code to be well organized, and unit tested,
+messages. 
+
+
+## Clean Matchers with Validators
+
+Validators allow your code to be well organized, and unit tested,
 while providing a clean implementation of the matcher, as shown here:
+
+```ruby
+RSpec::GraphQLResponse.add_matcher :foo_bar do |expected_value)
+  match do |actual_value|
+    foo_bar = RSpec::GraphQLResponse.validator(:foo_bar)
+
+    @result = foo_bar.validate(actual_value, expected_value)
+  end
+
+  failure_message do |response|
+    @result.reason
+  end
+end
+```
+
+## Add a Validator with a Failure Message
+
+```ruby
+RSpec::GraphQLResponse.add_validator :foo_bar do
+  # a regular failure message named `:nil`
+  failure_message :nil, "Can't validate nil"
+
+  # a lambda failure message named `:not_foo`
+  # this lets you pass data to the message so it can
+  # be more expressive of the failure reason
+  failure_message :not_foo, -> (actual, expected) { "Expected it to #{actual}, but it did not. found #{expected}" }
+  
+  validate do |actual, expected|
+    # fail for one reason
+    next fail_validation(:nil) if actual.nil?
+
+    # fail for another reason, with data passed
+    # to the failure message
+    next fail_validation(:not_foo, actual, expected) unless actual == expected
+
+    # no failures found, so pass it!
+    pass_validation
+  end
+end
+```
+
+### Method: `failure_message(name, message)`
+
+The `failure_message` method allows a message to be registered with a specific name and a message associated with that name. 
+
+`failure_message name, message`
+
+The `name` should be symbol which represents a reason for failure.
+
+The `message` can either be a string containing the failure message, or a lambda (proc) that returns a string with the message.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  failure_message :a_failure, "Failed because of a failure"
+
+  # ...
+end
+```
+
+Providing a lambda for the message allows the message to receive parameters and format the message using those parameters.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  failure_message :wrong_value, ->(value) { "Failed because #{value} is not 'foo'" }
+
+  # ...
+end
+```
+
+The failure messages can be referenced in the validation methods by calling `fail_validation` (see below)
+
+### Method: `validate(&validation_block)`
+
+Provide a validation method to determine if the actual value meets expectations. This validation method is most commonly
+used with the `expect(something).to ...` RSpec matcher syntax.
+
+The `&validation_block` will receive the actual value to validate as well as any other parameters that may need to be defined.
+There are no limitations on the number of parameters or their names.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  # ... failure_messages and other bits
+
+  validate do |actual, some_value|
+    # ... validation logic here
+
+    next fail_validation(:reason) if some_failure_criteria
+  end
+end
+```
+
+### Method: `validate_negated(&validation_block)`
+
+Provide a negated validation method to determine if the actual value meets expectations. This validation method is
+most commonly used with the negated expecation syntax, such as `expect(something).to_not ...`.
+
+The `&validation_block` will receive the actual value to validate as well as any other parameters that may need to be defined.
+There are no limitations on the number of parameters or their names.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  # ... failure_messages and other bits
+
+  validate_negated do |actual, some_value|
+    # ... negated validation logic here
+
+    next fail_validation(:reason) unless some_failure_criteria
+  end
+end
+```
+
+Remember that `negated` validation should prove that the specified condition does _not_ exist. For example, when writing
+an expectation such as `expect(response).to_not have_errors`, the `validate_negated` method needs to verify that there are
+no errors in the response.
+
+```ruby
+validate_negated do |response|
+  errors = response.fetch("errors", [])
+
+  # check for the negation of have_errors, meaning check to 
+  # make sure there are no errors
+  next fail_validation(:found_errors) unless errors.count == 0
+end
+```
+
+### Validation Failure
+
+When the actual value does not reflect any expected value, a failure can be noted by calling `next failure_message(name, [values])`.
+
+The `name` is a symbol which has been registered using the `failure_message` method (see above). And `[values]` are an optional
+array of values that will be provided to the failure message if the registered message is a lambda (proc).
+
+```ruby
+vadliate do |actual|
+
+  # something went wrong, better fail!
+  next fail_validation(:bad_thing) if actual.bad_value
+end
+```
+
+**IMPORTANT NOTE**
+
+There can be only _one_ valid reason for failure at a time. Therefore, as soon as a failure condition is met, the `fail_validation`
+method should be invoked. Then to prevent the rest of the method from executing, the `validate` or `validate_negates` method should
+be halted immediately. Due to the syntax requirements of ruby lambdas and procs, this is done with the `next` keyword.
+
+So be sure to call `next failure_message ...` and not just `failure_message`!
+
+### Validation Success
+
+If all validation checks pass, the final call in the `validate` or `validate_negated` methods should be `pass_validation`
+
+```ruby
+validate do |actual|
+  # ... check for failed conditions
+
+  # everything passed!
+  pass_validation
+end
+```
+
+The `pass_validation` method takes in no parameters, as a valid result does not provide a reason.

data/docs/configuration.md

@@ -0,0 +1,12 @@
+# RSpec::GraphQLResponse Configuration
+
+To get things rolling, add a configuration block to your `spec_helper.rb` (or other file that gets included in specs, as
+desired). Within this block, you'll need to provide the GraphQL Schema to use for query execution.
+
+```ruby
+RSpec::GraphQLResponse.configure |config| do
+
+  config.graphql_schema = MyGraphQLSchema
+
+end
+```

data/docs/execute_graphql.md

@@ -0,0 +1,50 @@
+# Executing GraphQL with Helper Method `execute_graphql`
+
+Simplifies execution of a graphql query, using `context` / `describe` level helper
+methods for configuring the query.
+
+```ruby
+RSPec.describe Cool::Stuff, type: :graphql do
+  let(:user) { create(:graphql_user) }
+  let(:search_name) { "Pet" }
+
+  graphql_operation <<-GQL
+    query SomeThing($name: String) {
+      characters(name: $name) {
+        id
+        name
+      }
+    }
+  GQL
+
+  graphql_variables do
+    {
+      name: search_name
+    }
+  end
+
+  grapql_context do
+    {
+      current_user: user
+    }
+  end
+
+  it "executes and does the thing with the vars and context" do
+    # ... expect things here
+  end
+end
+```
+
+## Available Configuration Methods
+
+### `graphql_operation`
+
+A string - most commonly a ruby heredoc - for the graphql query to execute
+
+### `graphql_variables`
+
+A hash of keys and values that the query expects to use
+
+### `graphql_context`
+
+A hash of keys and values that are passed to a query or mutation, as `context`, in that query or mutation's resolver method.

data/docs/graphql_spec_type.md

@@ -0,0 +1,14 @@
+# Custom Spec Type, `type: :grapql`
+
+To use the custom helpers and matchers provide by RSpec::GraphQLResponse, you need to specificy `type: :graphql` as 
+part of your spec's description.
+
+```ruby
+RSpec.describe My::Cool::Thing, type: :graphql do
+
+  # ... all of RSpec::GraphQLResponse is now available!
+
+end
+```
+
+With this `type` set, your specs will have access to all of the `RSpec::GraphQLResponse` features.

data/docs/have_operation.md

@@ -0,0 +1,46 @@
+# Validate a response operation with `have_operation(name)`
+
+Check for the presence of an operation's results. Useful when you want to ensure an operation exists before
+retrieving the operation's results.
+
+## Validate an Operation is Present
+
+```ruby
+RSpec.describe My::Characters, type: :graphql do
+  graphql_operation <<-GQL
+    query CharacterList {
+      characters {
+        id
+        name
+      }
+    }
+  GQL
+
+  it "has the characters" do
+
+    expect(response).to have_operation(:characters)
+
+  end
+end
+```
+
+## Validate an operation is NOT Present
+
+```ruby
+RSpec.describe My::Characters, type: :graphql do
+  graphql_operation <<-GQL
+    query CharacterList {
+      characters {
+        id
+        name
+      }
+    }
+  GQL
+
+  it "does not have books" do
+
+    expect(response).to_not have_operation(:books)
+
+  end
+end
+```

data/docs/operation.md

@@ -1,38 +1,3 @@
 # Using the `operation` helper
 
-The `operation` helper will dig through a response to find a data
-structure that looks like, 
-
-```ruby
-{
-  "data" => {
-    operation_name
-  }
-}
-```
-
-## Basic Use
-
-```ruby
-it "has characters" do
-  characters = operation(:characters)
-
-  expect(character).to include(
-    { id: 1, name: "Jam" },
-    # ...
-  )
-end
-```
-
-## Handling Nil
-
-If there is no `"data"` or no named operation for the name supplied, the
-`operation` helper will return `nil`
-
-```ruby
-it "returns nil if operation doesn't exist" do
-  character = operation(:something_that_does_not_exist)
-
-  expect(operation).to be_nil
-end
-```
+Deprecated. See [response_data](response_data.md) instead.