cucumber 5.2.0 → 7.0.0

Sign up to get free protection for your applications and to get access to all the features.
data/CONTRIBUTING.md CHANGED
@@ -1,73 +1,250 @@
1
- ## About to create a new Github Issue?
1
+ # Contributing to Cucumber
2
2
 
3
- We appreciate that. But before you do, please learn our basic rules:
3
+ Thank you for considering contributing to Cucumber!
4
4
 
5
- * This is not a support forum. If you have a question, please go to [The Cukes Google Group](http://groups.google.com/group/cukes).
6
- * Do you have an idea for a new feature? Then don't expect it to be implemented unless you or someone else sends a [pull request](https://help.github.com/articles/using-pull-requests). You might be better to start a discussion on [the google group](http://groups.google.com/group/cukes).
7
- * Reporting a bug? Please tell us:
8
- * which version of Cucumber you're using
9
- * which version of Ruby you're using.
10
- * How to reproduce it. Bugs with a failing test in a [pull request](https://help.github.com/articles/using-pull-requests) get fixed much quicker. Some bugs may never be fixed.
11
- * Want to paste some code or output? Put \`\`\` on a line above and below your code/output. See [GFM](https://help.github.com/articles/github-flavored-markdown)'s *Fenced Code Blocks* for details.
12
- * We love [pull requests](https://help.github.com/articles/using-pull-requests). But if you don't have a test to go with it we probably won't merge it.
5
+ This document will first introduce different ways to get involved before
6
+ focusing on how to contribute to the code.
13
7
 
14
- # Contributing to Cucumber
8
+ ## Code of Conduct
9
+
10
+ Everyone interacting in this codebase and issue tracker is expected to follow
11
+ the Cucumber [code of conduct](https://cucumber.io/conduct).
12
+
13
+ ## How can I contribute?
14
+
15
+ If you're reading this, you are certainly looking to contribute to the code. Cucumber
16
+ is not this single repository. It is made up of several packages around several
17
+ repositories. So before going further with the code, you may consider the
18
+ following first, in order to get your bearings.
19
+
20
+ If you just want to know how to contribute to the code, go to
21
+ [Contribute to the code](#contribute-to-the-code).
22
+
23
+ If you want to report an issue, or suggest an enhancement, go to
24
+ [Report bugs and submit feature requests](#report-bugs-and-submit-feature-requests).
25
+
26
+ ### Meet the community, the maintainers, and other Cucumber developers
27
+
28
+ Smartbear hosts a [community message board].
29
+ This is a good place to meet users, the community, and to ask questions.
30
+
31
+ You can also join the Cucumber Community Slack:
32
+ [register for an account][register-slack] then head over to [#intro][slack-intro].
33
+ This is the place to be to meet other contributors and find a mentor to help you
34
+ get started.
35
+
36
+ ### Test Cucumber
37
+
38
+ Testing Cucumber, especially new features, is a great way to contribute. We
39
+ cannot put a price on (early) feedback.
40
+
41
+ Keep an eye on our CHANGELOGS to discover new features. Test and experiment, and
42
+ submit your feedback through [issues](#report-bugs-and-submit-feature-requests),
43
+ the [community message board], or [Slack][community-slack].
44
+
45
+ ### Contribute to the documentation
46
+
47
+ [The documentation][cucumber-docs] is an important part of Cucumber. It is
48
+ essential that it remains simple and accurate. You can contribute to it via
49
+ [github.com/cucumber/docs](https://github.com/cucumber/docs).
50
+
51
+ ### Promote Cucumber
52
+
53
+ You don't know how to contribute but would like to help? Telling other people
54
+ about Cucumber on the Internet - social media, reviews, blogs - but also in real
55
+ life is already a big help! Join us on [Slack][community-slack] to share your
56
+ publication and to discover new ones.
57
+
58
+ ## Report bugs and submit feature requests
59
+
60
+ The short version is:
61
+
62
+ - Find the appropriate repository
63
+ - Try to check there is not already an issue or pull request that deals with
64
+ your bug or request
65
+ - Explain your issue and include as much details as possible to help other
66
+ people reproduce your problem or understand your request
67
+ - Consider submitting a pull request if you feel confident enough
68
+
69
+ You can find more details for each of these steps in the following sections.
70
+
71
+ ### Find the appropriate repository
72
+
73
+ The current repository, `cucumber-ruby`, is actually the tip of the iceberg. It
74
+ provides a user interface through a CLI, some built-in formatters, and the
75
+ execution environment you may know as the `World` object.
76
+
77
+ An important repository is [cucumber/common]. It is a mono-repo
78
+ with a lot of libraries. You will find there what is related to:
79
+
80
+ - parsing Gherkin documents - aka `.feature` files
81
+ - parsing tag expressions - the options you use to filter an execution with tags
82
+ - parsing Cucumber expressions - the expressions that link a Gherkin step to a
83
+ step definition
84
+ - everyting related to the HTML formatter
85
+
86
+ `cucumber-ruby` is also composed of:
87
+
88
+ - [cucumber-ruby-core]: this is the engine that will execute the test cases
89
+ computed from a parsed Gherkin document
90
+ - [cucumber-ruby-wire]: everything related to the Cucumber's wire protocol
91
+
92
+ Last but not least, there is also a repository for [cucumber-rails], the gem
93
+ that brings Cucumber to Rails 5.x and 6.x.
94
+
95
+ In any case, if your are not sure, best places to open an issue are the current
96
+ repository - `cucumber-ruby` - and the mono-repo at [cucumber/common].
97
+
98
+ ### Look for existing issues and pull requests
99
+
100
+ Search in [the current repository][cucumber-ruby-issues], in the
101
+ [mono-repo][cucumber/common-issues], but also in the
102
+ [whole cucumber organization][cucumber-issues] if the problem or feature has already
103
+ been reported. If you find an issue or pull request which is still open, add
104
+ comments to it instead of opening a new one.
105
+
106
+ If you're not sure, don't hesitate to just open a new issue. We can always merge
107
+ and de-duplicate later.
108
+
109
+ ### Submitting a pull request
110
+
111
+ When submitting a pull request:
112
+
113
+ - create a [draft pull request][how-to-create-a-draft-pr]
114
+ - try to follow the instructions in the [template](.github/PULL_REQUEST_TEMPLATE.md)
115
+ - if possible, [sign your commits]
116
+ - update CHANGELOG.md with your changes
117
+ - once the PR is ready, request for reviews
118
+
119
+ More info on [how to contribute to the code](#contribute-to-the-code) can be
120
+ found below.
121
+
122
+ ### Opening a new issue
123
+
124
+ To open a good issue, be clear and precise.
125
+
126
+ If you report a problem, the reader must be able to reproduce it easily.
127
+ Please do your best to create a [minimal, reproducible example][minimal-reproducible-example].
128
+
129
+ Consider submitting a pull request. Even if you think you cannot fix it by
130
+ yourself, a pull request with a failing test is always welcome.
131
+
132
+ If you request is for an enhancement - a new feature - try to be specific and
133
+ support your request with referenced facts and include examples to illustrate
134
+ your proposal.
135
+
136
+ ## Contribute to the code
137
+
138
+ ### Development environment
139
+
140
+ Development environment for `cucumber-ruby` is a simple Ruby environment with
141
+ Bundler. Use a [supported Ruby version](./README.md#supported-platforms), make
142
+ sure [Bundler] is set-up, and voilà!
143
+
144
+ You can then [fork][how-to-fork] and clone the repository. If your environment
145
+ is set-up properly, the following commands should install the dependencies and
146
+ execute all the tests successfully.
147
+
148
+ ```shell
149
+ bundle install
150
+ bundle exec rake
151
+ ```
152
+
153
+ You can now create a branch for your changes and [submit a pull request](#submitting-a-pull-request)!
154
+
155
+ If you want to check the code coverage during your development, execute
156
+ `bundle exec rake cov`.
157
+
158
+ ### Cucumber-ruby-core
159
+
160
+ As seen here: [Find the appropriate repository](#find-the-appropriate-repository),
161
+ you may need to work with other repositories in order to accomplish your
162
+ development. Beside the mono-repo in [cucumber/common], [cucumber-ruby-core] is
163
+ also a big piece of `cucumber-ruby`.
164
+
165
+ ### Using a local Gemfile
166
+
167
+ A local Gemfile allows you to use your prefer set of gems for your own
168
+ development workflow, like gems dedicated to debugging. Such gems are not part
169
+ of `cucumber-ruby` standard `Gemfile`.
170
+
171
+ `Gemfile.local`, `Gemfile.local.lock` and `.bundle` have been added to
172
+ `.gitignore` so local changes cannot be accidentaly commited and pushed to the
173
+ repository.
174
+
175
+ A `Gemfile.local` may look like this:
15
176
 
16
- The rest of this document is a guide for those maintaining Cucumber, and others who would like to submit patches.
177
+ ```ruby
178
+ # Gemfile.local
17
179
 
18
- ## Talking with other devs
180
+ # Include the regular Gemfile
181
+ eval File.read('Gemfile')
19
182
 
20
- You can chat with the core team on https://gitter.im/cucumber/contributors. We try to have office hours on Fridays.
183
+ # Include your favorites development gems
184
+ group :development do
185
+ gem 'byebug'
186
+ gem 'pry'
187
+ gem 'pry-byebug'
21
188
 
22
- ## Installing your own gems
189
+ gem 'debase', require: false
190
+ gem 'ruby-debug-ide', require: false
191
+ end
192
+ ```
23
193
 
24
- A `Gemfile.local`-file can be used to have your own gems installed to support
25
- your normal development workflow.
194
+ Then you can execute bundler with the `--gemfile` flag:
195
+ `bundle install --gemfile Gemfile.local`, or with an environment variable:
196
+ `BUNDLE_GEMFILE=Gemfile.local bundle [COMMAND]`.
26
197
 
27
- Example:
198
+ To use your local Gemfile per default, you can also execute
199
+ `bundle config set --local gemfile Gemfile.local`.
28
200
 
29
- ~~~ruby
30
- gem 'pry'
31
- gem 'pry-byebug'
32
- gem 'byebug'
33
- ~~~
201
+ ### First timer? Welcome!
34
202
 
35
- ## Note on Patches/Pull Requests
203
+ Looking for something simple to begin with? Look at issues with the label
204
+ '[good first issue](https://github.com/cucumber/cucumber-ruby/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)'.
36
205
 
37
- * Fork the project. Make a branch for your change.
38
- * Make your feature addition or bug fix.
39
- * Make sure your patch is well covered by tests. We don't accept changes to Cucumber that aren't tested.
40
- * Please do not change the Rakefile, version, or history.
41
- (if you want to have your own version, that is fine but
42
- bump version in a commit by itself so we can ignore when we merge your change)
43
- * Send us a pull request.
206
+ Remember: Cucumber is more than `cucumber-ruby`. You can look for good first
207
+ issues in [other cucumber reporistories](#find-the-appropriate-repository).
44
208
 
45
- ## Running tests
209
+ ### Having trouble getting started with the code? We're here to help!
46
210
 
47
- gem install bundler
48
- bundle install
49
- bundle exec rake
211
+ If you have trouble setting-up your development environment, or getting started
212
+ with the code, you can join us on [Slack][community-slack]. You will find there
213
+ a lot of contributors.
50
214
 
51
- To get code coverage results, run `bundle exec rake cov`
215
+ Full-time maintainers are also available. We would be please to have 1:1 pairing
216
+ sessions to help you getting started. Look for
217
+ [Matt Wynne](https://cucumberbdd.slack.com/team/U590XDLF3) or
218
+ [Aurélien Reeves](https://cucumberbdd.slack.com/team/U011BB95MC7) on
219
+ [Slack][community-slack].
52
220
 
53
- ## First timer? No problem!
221
+ ### Additional documentation and notice
54
222
 
55
- If you are new to the project or to OSS, check the label
56
- [Easy](https://github.com/cucumber/cucumber-ruby/labels/Easy). Also, you can
57
- help us to correct style violations reported here:
58
- [.rubocop_todo.yml](https://github.com/cucumber/cucumber-ruby/blob/master/.rubocop_todo.yml).
223
+ You can find additional documentation in the [docs](./docs) directory such as
224
+ (non-exhaustive list):
59
225
 
60
- ## Release Process
226
+ - [How to release cucumber-ruby](./docs/RELEASE_PROCESS.md) (for maintainers)
227
+ - [How to set-up a launch.json configuration for Visual Studio Code](./docs/vscode-example-launch-configuration.md)
61
228
 
62
- * Upgrade gems with `scripts/update-gemspec`
63
- * Bump the version number in `lib/cucumber/version`
64
- * Update `CHANGELOG.md` with the upcoming version number and create a new `In Git` section
65
- * Remove empty sections from `CHANGELOG.md`
66
- * Now release it:
67
229
 
68
- ```
69
- git commit -am "Release X.Y.Z"
70
- make release
71
- ```
230
+ <!-- Links -->
72
231
 
73
- * Finally, update the cucumber-ruby version in the [documentation project](https://cucumber.io/docs/installation/) in [versions.yaml](https://github.com/cucumber/docs.cucumber.io/blob/master/data/versions.yaml) file.
232
+ [community message board]: https://community.smartbear.com/t5/Cucumber-Open/bd-p/CucumberOS
233
+ [register-slack]: https://cucumberbdd-slack-invite.herokuapp.com/
234
+ [slack-intro]: https://cucumberbdd.slack.com/messages/C5WD8SA21/
235
+ [community-slack]: https://cucumberbdd.slack.com/
236
+ [cucumber-docs]: https://cucumber.io/docs/cucumber
237
+ [cucumber/common]: https://github.com/cucumber/common
238
+ [cucumber-ruby-core]: https://github.com/cucumber/cucumber-ruby-core
239
+ [cucumber-ruby-wire]: https://github.com/cucumber/cucumber-ruby-wire
240
+ [cucumber-rails]: https://github.com/cucumber/cucumber-rails
241
+ [cucumber-ruby-issues]: https://github.com/cucumber/cucumber-ruby/search?q=is%3Aissue
242
+ [cucumber/common-issues]: https://github.com/cucumber/common/search?q=is%3Aissue
243
+ [cucumber-issues]: https://github.com/search?q=is%3Aissue+user%3Acucumber
244
+ [how-to-create-a-draft-pr]: https://docs.github.com/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
245
+ [how-to-fork]: https://docs.github.com/github/collaborating-with-pull-requests/working-with-forks/about-forks
246
+ [sign your commits]: https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/signing-commits
247
+ [minimal-reproducible-example]: https://stackoverflow.com/help/minimal-reproducible-example
248
+ [RVM]: https://rvm.io/
249
+ [rbenv]: https://github.com/rbenv/rbenv
250
+ [Bundler]: https://bundler.io/
data/README.md CHANGED
@@ -1,38 +1,158 @@
1
+ <p align="center">
2
+ <img src="./.github/img/cucumber-open-logo.png" alt="Cucumber Open - Supported by Smartbear" width="428" />
3
+ </p>
4
+
5
+ # Cucumber
6
+
1
7
  [![OpenCollective](https://opencollective.com/cucumber/backers/badge.svg)](https://opencollective.com/cucumber)
2
8
  [![OpenCollective](https://opencollective.com/cucumber/sponsors/badge.svg)](https://opencollective.com/cucumber)
3
-
9
+ [![pull requests](https://oselvar.com/api/badge?label=pull%20requests&csvUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fcucumber%2Foselvar-github-metrics%2Fmain%2Fdata%2Fcucumber%2Fcucumber-ruby%2FpullRequests.csv)](https://oselvar.com/github/cucumber/oselvar-github-metrics/main/cucumber/cucumber-ruby)
10
+ [![issues](https://oselvar.com/api/badge?label=issues&csvUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fcucumber%2Foselvar-github-metrics%2Fmain%2Fdata%2Fcucumber%2Fcucumber-ruby%2Fissues.csv)](https://oselvar.com/github/cucumber/oselvar-github-metrics/main/cucumber/cucumber-ruby)
4
11
  [![CircleCI](https://circleci.com/gh/cucumber/cucumber-ruby.svg?style=svg)](https://circleci.com/gh/cucumber/cucumber-ruby)
5
-
6
12
  [![Code Climate](https://codeclimate.com/github/cucumber/cucumber-ruby.svg)](https://codeclimate.com/github/cucumber/cucumber-ruby)
7
- [![Coverage Status](https://coveralls.io/repos/cucumber/cucumber-ruby/badge.svg?branch=master)](https://coveralls.io/r/cucumber/cucumber-ruby?branch=master)
8
-
9
- # Cucumber
13
+ [![Coverage Status](https://coveralls.io/repos/cucumber/cucumber-ruby/badge.svg?branch=main)](https://coveralls.io/r/cucumber/cucumber-ruby?branch=main)
10
14
 
11
15
  Cucumber is a tool for running automated tests written in plain language. Because they're
12
16
  written in plain language, they can be read by anyone on your team. Because they can be
13
17
  read by anyone, you can use them to help improve communication, collaboration and trust on
14
18
  your team.
15
19
 
16
- Where to get more info:
20
+ <p align="center">
21
+ <img src="./.github/img/gherkin-example.png" alt="Cucumber Gherkin Example" width="728" />
22
+ </p>
23
+
24
+ This is the Ruby implementation of Cucumber. Cucumber is also available for [JavaScript](https://github.com/cucumber/cucumber-js),
25
+ [Java](https://github.com/cucumber/cucumber-jvm), and a lot of other languages. You can find a list of implementations here: https://cucumber.io/docs/installation/.
26
+
27
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for info on contributing to Cucumber (issues, PRs, etc.).
28
+
29
+ Everyone interacting in this codebase and issue tracker is expected to follow the
30
+ Cucumber [code of conduct](https://cucumber.io/conduct).
31
+
32
+ ## Installation
33
+
34
+ Cucumber for Ruby is a Ruby gem. Install it as you would install any gem: add
35
+ `cucumber` to your Gemfile:
36
+
37
+ gem 'cucumber'
38
+
39
+ then install it:
40
+
41
+ $ bundle
42
+
43
+ or install the gem directly:
44
+
45
+ $ gem install cucumber
46
+
47
+ Later in this document, bundler is considered being used so all commands are using
48
+ `bundle exec`. If this is not the case for you, execute `cucumber` directly, without
49
+ `bundle exec`.
50
+
51
+ ### Supported platforms
52
+
53
+ - Ruby 3.0
54
+ - Ruby 2.7
55
+ - Ruby 2.6
56
+ - Ruby 2.5
57
+ - Ruby 2.4
58
+ - Ruby 2.3
59
+ - JRuby 9.2 (with [some limitations](https://github.com/cucumber/cucumber-ruby/blob/main/docs/jruby-limitations.md))
60
+
61
+ ### Ruby on Rails
62
+
63
+ Using Ruby on Rails? You can use [cucumber-rails](https://github.com/cucumber/cucumber-rails)
64
+ to bring Cucumber into your Rails project.
65
+
66
+ ## Usage
67
+
68
+ ### Initialization
69
+
70
+ If you need to, initialize your `features` directory with
71
+
72
+ $ bundle exec cucumber --init
73
+
74
+ This will create the following directories and files if they do not exist already:
75
+
76
+ features
77
+ ├── step_definitions
78
+ └── support
79
+ └── env.rb
80
+
81
+ ### Create your specification
82
+
83
+ Create a file named `rule.feature` in the `features` directory with:
84
+
85
+ ```gherkin
86
+ # features/rule.feature
87
+
88
+ Feature: Rule Sample
89
+
90
+ Rule: This is a rule
91
+
92
+ Example: A passing example
93
+ Given this will pass
94
+ When I do an action
95
+ Then some results should be there
96
+
97
+ Example: A failing example
98
+ Given this will fail
99
+ When I do an action
100
+ Then some results should be there
101
+
102
+ ```
103
+
104
+ ### Automate your specification
105
+
106
+ And a file named `steps.rb` in `features/step_definitions` with:
107
+
108
+ ```ruby
109
+ # features/step_definitions/steps.rb
110
+
111
+ Given("this will pass") do
112
+ @this_will_pass = true
113
+ end
114
+
115
+ Given("this will fail") do
116
+ @this_will_pass = false
117
+ end
118
+
119
+ When("I do an action") do
120
+ end
121
+
122
+ Then("some results should be there") do
123
+ expect(@this_will_pass)
124
+ end
125
+ ```
126
+
127
+ ### Run Cucumber
128
+
129
+ $ bundle exec cucumber
130
+
131
+ To execute a single feature file:
132
+
133
+ $ bundle exec cucumber features/rule.feature
134
+
135
+ To execute a single example, indicates the line of the name of the example:
136
+
137
+ $ bundle exec cucumber features/rule.feature:7
138
+
139
+ To summarize the results on the standard output, and writte a HTML report on disk:
140
+
141
+ $ bundle exec cucumber --format summary --format html --out report.html
17
142
 
18
- * The main website: https://cucumber.io/
19
- * Documentation: https://cucumber.io/docs
20
- * Ruby API Documentation: http://www.rubydoc.info/github/cucumber/cucumber-ruby/
21
- * Support forum: https://groups.google.com/group/cukes
22
- * Chat: ([Slack](https://cucumber.io/support#slack) and [Gitter](https://cucumber.io/support#gitter))
143
+ For more command line options
23
144
 
24
- See [CONTRIBUTING.md](CONTRIBUTING.md) for info on contributing to Cucumber.
145
+ $ bundle exec cucumber --help
25
146
 
26
- ## Supported platforms
27
- * Ruby 2.6
28
- * Ruby 2.5
29
- * Ruby 2.4
30
- * Ruby 2.3
31
- * JRuby 9.2 (with [some limitations](https://github.com/cucumber/cucumber-ruby/blob/master/docs/jruby-limitations.md))
147
+ You can also find documentation on the command line possibilities in
148
+ [features/docs/cli](features/docs/cli).
32
149
 
33
- ## Code of Conduct
150
+ ## Documentation and support
34
151
 
35
- Everyone interacting in this codebase and issue tracker is expected to follow the Cucumber [code of conduct](https://github.com/cucumber/cucumber/blob/master/CODE_OF_CONDUCT.md).
152
+ - Getting started, writing features, step definitions, and more: https://cucumber.io/docs
153
+ - Ruby API Documentation: http://www.rubydoc.info/github/cucumber/cucumber-ruby/
154
+ - Community support forum: https://community.smartbear.com/t5/Cucumber-Open/bd-p/CucumberOS
155
+ - Slack: [register for an account](https://cucumberbdd-slack-invite.herokuapp.com/) then head over to [#intro](https://cucumberbdd.slack.com/messages/C5WD8SA21/)
36
156
 
37
157
  ## Copyright
38
158