1
0
Fork 0
mirror of https://github.com/teamcapybara/capybara.git synced 2022-11-09 12:08:07 -05:00

Markup API doc in Markdown style (#2210) [ci skip]

* Markup API doc in Markdown style

- Specify `--markup markdown` option to YARD.
- Add and publish `.yardopts` file, instead of giving the option in `Rakefile`.
  This `.yardopts` file allows to use the same options on <https://www.rubydoc.info/>.
- Rewrite the `Capybara.configure` method doc because it's broken in Markdown style.
- Fix `Capybara::Selector` doc in markdown style
This commit is contained in:
Masafumi Koba 2019-05-28 21:17:38 +09:00 committed by Thomas Walpole
parent 435eba6fd6
commit 2f3aa8f829
6 changed files with 127 additions and 121 deletions

1
.gitignore vendored
View file

@ -21,3 +21,4 @@ bundler_stubs
bin
gem-private_key.pem
save_path_tmp
vendor/bundle

1
.yardopts Normal file
View file

@ -0,0 +1 @@
--markup markdown

View file

@ -41,7 +41,6 @@ task rack_smoke: %i[rubocop spec_rack]
YARD::Rake::YardocTask.new do |t|
t.files = ['lib/**/*.rb']
t.options = %w[--markup=markdown]
end
Cucumber::Rake::Task.new(:cucumber) do |task|

View file

@ -16,7 +16,7 @@ Gem::Specification.new do |s|
s.description = 'Capybara is an integration testing tool for rack based web applications. '\
'It simulates how a user would interact with a website'
s.files = Dir.glob('{lib,spec}/**/*') + %w[README.md History.md License.txt]
s.files = Dir.glob('{lib,spec}/**/*') + %w[README.md History.md License.txt .yardopts]
s.homepage = 'https://github.com/teamcapybara/capybara'
s.metadata = {

View file

@ -66,39 +66,44 @@ module Capybara
# config.app_host = 'http://www.google.com'
# end
#
# === Configurable options
# #### Configurable options
#
# [app_host = String/nil] The default host to use when giving a relative URL to visit, must be a valid URL e.g. http://www.example.com
# [always_include_port = Boolean] Whether the Rack server's port should automatically be inserted into every visited URL unless another port is explicitly specified (Default: false)
# [asset_host = String] Where dynamic assets are hosted - will be prepended to relative asset locations if present (Default: nil)
# [run_server = Boolean] Whether to start a Rack server for the given Rack app (Default: true)
# [raise_server_errors = Boolean] Should errors raised in the server be raised in the tests? (Default: true)
# [server_errors = Array\<Class\>] Error classes that should be raised in the tests if they are raised in the server and {configure raise_server_errors} is true (Default: [Exception])
# [default_selector = :css/:xpath] Methods which take a selector use the given type by default (Default: :css)
# [default_max_wait_time = Numeric] The maximum number of seconds to wait for asynchronous processes to finish (Default: 2)
# [ignore_hidden_elements = Boolean] Whether to ignore hidden elements on the page (Default: true)
# [automatic_reload = Boolean] Whether to automatically reload elements as Capybara is waiting (Default: true)
# [save_path = String] Where to put pages saved through save_(page|screenshot), save_and_open_(page|screenshot) (Default: Dir.pwd)
# [automatic_label_click = Boolean] Whether {Capybara::Node::Element#choose Element#choose}, {Capybara::Node::Element#check Element#check}, {Capybara::Node::Element#uncheck Element#uncheck} will attempt to click the associated label element if the checkbox/radio button are non-visible (Default: false)
# [enable_aria_label = Boolean] Whether fields, links, and buttons will match against aria-label attribute (Default: false)
# [reuse_server = Boolean] Reuse the server thread between multiple sessions using the same app object (Default: true)
# [threadsafe = Boolean] Whether sessions can be configured individually (Default: false)
# [server = Symbol] The name of the registered server to use when running the app under test (Default: :default which uses puma)
# [default_set_options = Hash] The default options passed to {Capybara::Node::Element#set Element#set} (Default: {})
# [test_id = Symbol/String/nil] Optional attribute to match locator aginst with builtin selectors along with id (Default: nil)
# [predicates_wait = Boolean] Whether Capybara's predicate matchers use waiting behavior by default (Default: true)
# [default_normalize_ws = Boolean] Whether text predicates and matchers use normalize whitespace behaviour (Default: false)
# [allow_gumbo = Boolean] When `nokogumbo` is available, whether it will be used to parse HTML strings (Default: false)
# [match = :one/:first/:prefer_exact/:smart] The matching strategy to find nodes (Default: :smart)
# [exact = Boolean] Whether locators are matched exactly or with substrings. Only affects selector conditions written using the XPath#is method (Default: false)
# [exact_text = Boolean] Whether the text matchers and `:text` filter match exactly or on substrings (Default: false)
# - **allow_gumbo** (Boolean = `false`) - When `nokogumbo` is available, whether it will be used to parse HTML strings.
# - **always_include_port** (Boolean = `false`) - Whether the Rack server's port should automatically be inserted into every visited URL
# unless another port is explicitly specified.
# - **app_host** (String, `nil`) - The default host to use when giving a relative URL to visit, must be a valid URL e.g. `http://www.example.com`.
# - **asset_host** (String = `nil`) - Where dynamic assets are hosted - will be prepended to relative asset locations if present.
# - **automatic_label_click** (Boolean = `false`) - Whether {Capybara::Node::Element#choose Element#choose}, {Capybara::Node::Element#check Element#check},
# {Capybara::Node::Element#uncheck Element#uncheck} will attempt to click the associated `<label>` element if the checkbox/radio button are non-visible.
# - **automatic_reload** (Boolean = `true`) - Whether to automatically reload elements as Capybara is waiting.
# - **default_max_wait_time** (Numeric = `2`) - The maximum number of seconds to wait for asynchronous processes to finish.
# - **default_normalize_ws** (Boolean = `false`) - Whether text predicates and matchers use normalize whitespace behavior.
# - **default_selector** (`:css`, `:xpath` = `:css`) - Methods which take a selector use the given type by default. See also {Capybara::Selector}.
# - **default_set_options** (Hash = `{}`) - The default options passed to {Capybara::Node::Element#set Element#set}.
# - **enable_aria_label** (Boolean = `false`) - Whether fields, links, and buttons will match against `aria-label` attribute.
# - **exact** (Boolean = `false`) - Whether locators are matched exactly or with substrings. Only affects selector conditions
# written using the `XPath#is` method.
# - **exact_text** (Boolean = `false`) - Whether the text matchers and `:text` filter match exactly or on substrings.
# - **ignore_hidden_elements** (Boolean = `true`) - Whether to ignore hidden elements on the page.
# - **match** (`:one`, `:first`, `:prefer_exact`, `:smart` = `:smart`) - The matching strategy to find nodes.
# - **predicates_wait** (Boolean = `true`) - Whether Capybara's predicate matchers use waiting behavior by default.
# - **raise_server_errors** (Boolean = `true`) - Should errors raised in the server be raised in the tests?
# - **reuse_server** (Boolean = `true`) - Whether to reuse the server thread between multiple sessions using the same app object.
# - **run_server** (Boolean = `true`) - Whether to start a Rack server for the given Rack app.
# - **save_path** (String = `Dir.pwd`) - Where to put pages saved through {Capybara::Session#save_page save_page}, {Capybara::Session#save_screenshot save_screenshot},
# {Capybara::Session#save_and_open_page save_and_open_page}, or {Capybara::Session#save_and_open_screenshot save_and_open_screenshot}.
# - **server** (Symbol = `:default` (which uses puma)) - The name of the registered server to use when running the app under test.
# - **server_errors** (Array\<Class> = `[Exception]`) - Error classes that should be raised in the tests if they are raised in the server
# and {configure raise_server_errors} is `true`.
# - **test_id** (`Symbol`, `String`, `nil` = `nil`) - Optional attribute to match locator against with built-in selectors along with id.
# - **threadsafe** (Boolean = `false`) - Whether sessions can be configured individually.
#
# === DSL Options
# #### DSL Options
#
# when using capybara/dsl, the following options are also available:
# When using `capybara/dsl`, the following options are also available:
#
# [default_driver = Symbol] The name of the driver to use by default. (Default: :rack_test)
# [javascript_driver = Symbol] The name of a driver to use for JavaScript enabled tests. (Default: :selenium)
# - **default_driver** (Symbol = `:rack_test`) - The name of the driver to use by default.
# - **javascript_driver** (Symbol = `:selenium`) - The name of a driver to use for JavaScript enabled tests.
#
def configure
yield config

View file

@ -5,7 +5,7 @@ require 'capybara/selector/selector'
require 'capybara/selector/definition'
#
# == Built-in Selectors
# ### Built-in Selectors
#
# * **:xpath** - Select elements by XPath expression
# * Locator: An XPath expression
@ -19,47 +19,47 @@ require 'capybara/selector/definition'
# * **:field** - Select field elements (input [not of type submit, image, or hidden], textarea, select)
# * Locator: Matches against the id, {Capybara.configure test_id} attribute, name, or placeholder
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :placeholder (String) - Matches the placeholder attribute
# * :type (String) - Matches the type attribute of the field or element type for 'textarea' and 'select'
# * :readonly (Boolean)
# * :with (String) - Matches the current value of the field
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :checked (Boolean) - Match checked fields?
# * :unchecked (Boolean) - Match unchecked fields?
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match fields that accept multiple values
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :placeholder (String) - Matches the placeholder attribute
# * :type (String) - Matches the type attribute of the field or element type for 'textarea' and 'select'
# * :readonly (Boolean)
# * :with (String) - Matches the current value of the field
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :checked (Boolean) - Match checked fields?
# * :unchecked (Boolean) - Match unchecked fields?
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match fields that accept multiple values
# * :style (String, Regexp, Hash)
#
# * **:fieldset** - Select fieldset elements
# * Locator: Matches id or contents of wrapped legend
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches id attribute
# * :legend (String) - Matches contents of wrapped legend
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches id attribute
# * :legend (String) - Matches contents of wrapped legend
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :style (String, Regexp, Hash)
#
# * **:link** - Find links (`<a>` elements with an href attribute)
# * Locator: Matches the id or title attributes, or the string content of the link, or the alt attribute of a contained img element
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :title (String) - Matches the title attribute
# * :alt (String) - Matches the alt attribute of a contained img element
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :href (String, Regexp, nil, false) - Matches the normalized href of the link, if nil will find `<a>` elements with no href attribute, if false ignores href
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :title (String) - Matches the title attribute
# * :alt (String) - Matches the alt attribute of a contained img element
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :href (String, Regexp, nil, false) - Matches the normalized href of the link, if nil will find `<a>` elements with no href attribute, if false ignores href
# * :style (String, Regexp, Hash)
#
# * **:button** - Find buttons ( input [of type submit, reset, image, button] or button elements )
# * Locator: Matches the id, {Capybara.configure test_id} attribute, name, value, or title attributes, string content of a button, or the alt attribute of an image type button or of a descendant image of a button
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :title (String) - Matches the title attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :value (String) - Matches the value of an input button
# * :type
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :title (String) - Matches the title attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :value (String) - Matches the value of an input button
# * :type
# * :style (String, Regexp, Hash)
#
# * **:link_or_button** - Find links or buttons
# * Locator: See :link and :button selectors
@ -67,67 +67,67 @@ require 'capybara/selector/definition'
# * **:fillable_field** - Find text fillable fields ( textarea, input [not of type submit, image, radio, checkbox, hidden, file] )
# * Locator: Matches against the id, {Capybara.configure test_id} attribute, name, or placeholder
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :placeholder (String) - Matches the placeholder attribute
# * :with (String) - Matches the current value of the field
# * :type (String) - Matches the type attribute of the field or element type for 'textarea'
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match fields that accept multiple values
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :placeholder (String) - Matches the placeholder attribute
# * :with (String) - Matches the current value of the field
# * :type (String) - Matches the type attribute of the field or element type for 'textarea'
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match fields that accept multiple values
# * :style (String, Regexp, Hash)
#
# * **:radio_button** - Find radio buttons
# * Locator: Match id, {Capybara.configure test_id} attribute, name, or associated label text
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :checked (Boolean) - Match checked fields?
# * :unchecked (Boolean) - Match unchecked fields?
# * :disabled (Boolean) - Match disabled field?
# * :option (String) - Match the value
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :checked (Boolean) - Match checked fields?
# * :unchecked (Boolean) - Match unchecked fields?
# * :disabled (Boolean) - Match disabled field?
# * :option (String) - Match the value
# * :style (String, Regexp, Hash)
#
# * **:checkbox** - Find checkboxes
# * Locator: Match id, {Capybara.configure test_id} attribute, name, or associated label text
# * Filters:
# * *:id (String, Regexp, XPath::Expression) - Matches the id attribute
# * *:name (String) - Matches the name attribute
# * *:class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * *:checked (Boolean) - Match checked fields?
# * *:unchecked (Boolean) - Match unchecked fields?
# * *:disabled (Boolean) - Match disabled field?
# * *:option (String) - Match the value
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :checked (Boolean) - Match checked fields?
# * :unchecked (Boolean) - Match unchecked fields?
# * :disabled (Boolean) - Match disabled field?
# * :option (String) - Match the value
# * :style (String, Regexp, Hash)
#
# * **:select** - Find select elements
# * Locator: Match id, {Capybara.configure test_id} attribute, name, placeholder, or associated label text
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :placeholder (String) - Matches the placeholder attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match fields that accept multiple values
# * :options (Array<String>) - Exact match options
# * :with_options (Array<String>) - Partial match options
# * :selected (String, Array<String>) - Match the selection(s)
# * :with_selected (String, Array<String>) - Partial match the selection(s)
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :placeholder (String) - Matches the placeholder attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match fields that accept multiple values
# * :options (Array<String>) - Exact match options
# * :with_options (Array<String>) - Partial match options
# * :selected (String, Array<String>) - Match the selection(s)
# * :with_selected (String, Array<String>) - Partial match the selection(s)
# * :style (String, Regexp, Hash)
#
# * **:option** - Find option elements
# * Locator: Match text of option
# * Filters:
# * :disabled (Boolean) - Match disabled option
# * :selected (Boolean) - Match selected option
# * :disabled (Boolean) - Match disabled option
# * :selected (Boolean) - Match selected option
#
# * **:datalist_input**
# * Locator:
# * Filters:
# * :disabled
# * :name
# * :placeholder
# * :disabled
# * :name
# * :placeholder
#
# * **:datalist_option**
# * Locator:
@ -135,29 +135,29 @@ require 'capybara/selector/definition'
# * **:file_field** - Find file input elements
# * Locator: Match id, {Capybara.configure test_id} attribute, name, or associated label text
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match field that accepts multiple values
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Matches the id attribute
# * :name (String) - Matches the name attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :disabled (Boolean) - Match disabled field?
# * :multiple (Boolean) - Match field that accepts multiple values
# * :style (String, Regexp, Hash)
#
# * **:label** - Find label elements
# * Locator: Match id or text contents
# * Filters:
# * :for (Element, String, Regexp) - The element or id of the element associated with the label
# * :for (Element, String, Regexp) - The element or id of the element associated with the label
#
# * **:table** - Find table elements
# * Locator: id or caption text of table
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Match id attribute of table
# * :caption (String) - Match text of associated caption
# * :class ((String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :style (String, Regexp, Hash)
# * :with_rows (Array<Array<String>>, Array<Hash<String, String>>) - Partial match `<td>` data - visibility of `<td>` elements is not considered
# * :rows (Array<Array<String>>) - Match all `<td>`s - visibility of `<td>` elements is not considered
# * :with_cols (Array<Array<String>>, Array<Hash<String, String>>) - Partial match `<td>` data - visibility of `<td>` elements is not considered
# * :cols (Array<Array<String>>) - Match all `<td>`s - visibility of `<td>` elements is not considered
# * :id (String, Regexp, XPath::Expression) - Match id attribute of table
# * :caption (String) - Match text of associated caption
# * :class ((String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :style (String, Regexp, Hash)
# * :with_rows (Array<Array<String>>, Array<Hash<String, String>>) - Partial match `<td>` data - visibility of `<td>` elements is not considered
# * :rows (Array<Array<String>>) - Match all `<td>`s - visibility of `<td>` elements is not considered
# * :with_cols (Array<Array<String>>, Array<Hash<String, String>>) - Partial match `<td>` data - visibility of `<td>` elements is not considered
# * :cols (Array<Array<String>>) - Match all `<td>`s - visibility of `<td>` elements is not considered
#
# * **:table_row** - Find table row
# * Locator: Array<String>, Hash<String,String> table row `<td>` contents - visibility of `<td>` elements is not considered
@ -165,10 +165,10 @@ require 'capybara/selector/definition'
# * **:frame** - Find frame/iframe elements
# * Locator: Match id or name
# * Filters:
# * :id (String, Regexp, XPath::Expression) - Match id attribute
# * :name (String) - Match name attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :style (String, Regexp, Hash)
# * :id (String, Regexp, XPath::Expression) - Match id attribute
# * :name (String) - Match name attribute
# * :class (String, Array<String>, Regexp, XPath::Expression) - Matches the class(es) provided
# * :style (String, Regexp, Hash)
#
# * **:element**
# * Locator: Type of element ('div', 'a', etc) - if not specified defaults to '*'