cucumber / docs Goto Github PK
View Code? Open in Web Editor NEWCucumber user documentation
Home Page: https://cucumber.io/docs/installation/
License: MIT License
Cucumber user documentation
Home Page: https://cucumber.io/docs/installation/
License: MIT License
For Java
'info.cukes' should be 'io.cucumber'
(As discussed on Slack between @aslakhellesoy and myself:)
All docs updates should be in the new docs.cucumber.io repo
Prevent duplicated / out of sync documentation, and/or rework to update documentation from other sources into this repo.
Add info to all individual sets of documentation (at least as mentioned in the README of this repo), placing a "do not update" warning somewhere, with an link pointing to this project for documentation updates.
Information should be placed where contributors are most likely to see that warning, starting with:
Add text with a link to this repo to the following repos/documents:
Note: Do not update documentation in this repo. We are busy adding old documentation to a new repository docs.cucumber.io to replace the current documentation on cucumber.io.
Please make ALL contributions to the documentation here.
Text should be added to:
Point CONTRIBUTING.md's in various repos to "Contributing-to-documentation.md" in docs.cucumber.io:
Contributing.md file (s) in various repos:
We need some kind of decent search:
Two obvious options are:
I suggest we implement both as long as it isn't too time consuming, and contrast and compare.
Nice to have: find them automatically
https://app.netlify.com/sites/cucumber/deploys/5a3cc0c88198767e07da8ff5
data from @mlvandijk in #89 :
The following links are failing on HTMLProoofer:
9:23:02 AM: * External link http://watirmelon.com/2011/01/21/my-simple-cucumber-watir-page-object-pattern-framework failed: 404 No error
External link http://watirmelon.com/2011/01/23/reducing-step-explosion-by-decoupling-cucumber-steps-from-your-gui failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/05/18/specification-by-example-a-love-story failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/07/04/the-elements-of-cucumber-style failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/07/04/use-cucumber-feature-folders-for-functional-organization-tags-for-non-functional-classification failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/04/capturing-screenshots-in-watir-webdriver-cucumber failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/07/keeping-the-browser-open-when-youre-writing-a-cucumber-test failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/08/making-your-cucumber-step-definitions-more-readable-with-rspec-binary-matchers failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/10/capturing-page-performance-times-with-my-watirmeloncucumber-framework failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/29/running-your-watir-webdriver-tests-in-the-cloud-for-free failed: 404 No error
I've checked one of them and am getting:"Oops! That page can’t be found."
So these links need to be updated/removed(?)
From @aslakhellesoy on March 21, 2017 23:47
It's a bit daunting for newcomers to find out where and how to make changes.
There are some docs about this in the root folder (some of them are out of date). CONTRIBUTING.md
is too long and boring.
Let's steal shamelessly from these great projects (with credits):
Some general guides for inspiration:
Copied from original issue: cucumber/common#167
I followed the docs and ran into an issue similar to this -
I needed to make 2 fixes add the cucumber-core
to my dependencies and also increment the cucumber-junit
version to cucumber-java's
versions (2.0.X)
I would like to send a pull for this if the community thinks this is a valid concern for beginners.
I'm just cleaning up tickets on http://github.com/cucumber/website and there are four pull requests sitting open on the docs that have been there for a long time:
cucumber/website#8
cucumber/website#4
cucumber/website#3
cucumber/website#1
I'm going to close all of them now, but I suggest someone checks them over to see if anything valuable can be salvaged.
Might be related to this.
We use #
on in page headers, which render as H1. (which should probably be rendered as H2 anyway), and the in-page toc seems to think #
and ##
are of equal importance.
See https://cucumber.io/docs/reference/state
I don't know how to set a before hook, I'd like to read that page.
Most of the pages in the current version of the docs don't vary according to your programming language, and it's misleading to show the language switcher tabs on those pages.
It would be better if we can have them only appear when we do have a page that has cross-platform docs on it.
@aslakhellesoy how would we go about doing that? We could disable the tabs by default and put a flag in the YAML frontmatter on the pages that do have cross-platform docs, for example.
Current behaviour
There's a small scrollable window that shows (part of) an open collective page containing input fields.
Expected behaviour
An Open Collective logo with link to the Cucumber contributions page
TOC doesn't seem to work for polyglot pages (when headings are inside language block).
For example: https://sw-menu--cucumber.netlify.com/installation/
As we're not using these we should remove them for clarity.
And possibly replace with with a comment pointing to themes/cucumber-hugo/layouts/partials/navbar.html
@plaindocs did you add the realartists.com webhook? What is it for?
#Brain dump of links in sw-reorg
which either need turning into proper markdown links [text](/path/to/file)
or have the [[text]]
removing.
Running grep "\[\["
in the content
dir should give you an updated list.
wiki/cucumber-backgrounder.md
364:As with `Feature`, `Scenario` is used only for identification when reporting failures and to document a piece of the work. The clauses (*steps*) that make up a Scenario each begin with one of: Given, When, Then, And and But (and sometimes **\***). These are all [[Gherkin]] keywords / Cucumber methods that take as their argument the string that follows. They are the steps that Cucumber will report as passing, failing or pending based on the results of the corresponding step matchers in the step_definitions.rb files. The five keywords (and **\***) are all equivalent to one another and completely interchangeable.
489:Always keep in mind that Cucumber is simply a DSL wrapper around the Ruby language whose full expressiveness remains available to you in the step definition files (*but not in the feature files*). On the other hand, do not lose sight that every step called as such in a step definition file is first parsed by [[Gherkin]] and therefore must conform to the same syntax as used in feature files.
wiki/autotest-integration.md
57:If you get an error like `When using several—format options only one of them can be without a file (RuntimeError)` when running features with autospec, you are probably accidentally requiring 'spec'. Read about the solution on [[Troubleshooting]].
implementations/jvm.md
14:Please see the [[general reference]] for features that are
73:- [[Android Runner]]
149:The [JUnit Runner](#junit-runner) and [[Android Runner]] can also pick
187:Usage: java cucumber.api.cli.Main [options] [[[FILE|DIR][:LINE[:LINE]*] ]+ | @FILE ]
320:If you prefer to use a [[Data Table]] to define a list you can do that too:
implementations/ruby/ruby-on-rails.md
83:If you're on an OS that supports fork we recommend you use [[Spork and --drb]] as this lets you start cucumber faster:
163:Remember that you need AUTOFEATURE=true for autospec to include cucumber features. See [[Running Features]] and \[\[Autotest Integration]] for more info.
176:There are two special [[tags]] you can use to change how Cucumber runs your scenarios
180:By default all scenarios will run within a database transaction that is rolled back at the end. However, scenarios tagged with `@no-txn` will run **without** a transaction. This can be useful when you have to deal with [[Browsers and Transactions]]. Beware that this will leave data in your database after that scenario, which can lead to hard-to-debug failures in subsequent scenarios. If you use this, we recommend you create a Before block that will explicitly put your database in a known state, for example using [DatabaseCleaner](https://github.com/bmabey/database_cleaner)
implementations/ruby/calling-steps-from-step-definitions.md
63:Sometimes you want to call a step that has been designed to take [[Multiline Step Arguments]], for example:
implementations/php.md
95:The per feature and per table approach can be accomplished using [[hooks]].
about/blog-posts.md
10:Please add any helpful blog posts that you have found or written about all things Cucumber. Also see [[Related Tools]].
about/get-in-touch.md
41:- And finally, tell us how to reproduce the error, as described on the [[Contributing]] page.
about/contributing.md
12:Before you [[get in touch]] and file a ticket in the issue tracker, make sure you have tried the latest gem. Also try to \[\[install]] the latest code from Git. This way you don't waste the developers' time by reporting a bug that has already been fixed.
18:The only way we can fix a bug is to reproduce it first. If reproducing the bug requires setting up a project, please write a [[Cucumber Feature]] that demonstrates the bug. When you have done that, mention it in your ticket or send a pull request.
24:Start by creating a ticket. Then, create a [[Cucumber Feature]] and start implementing it. It also helps if you add RSpec specs for the low level code.
gherkin/gherkin-reference.md
10:the [[documentation overview]] for links to platform-specific documentation.
194:You can also use placeholders in [[Multiline Step Arguments]].
gherkin/feature-introduction.md
14:(or localized equivalent; Gherkin is localized for [[dozens of languages|Spoken
cucumber/step-definitions.md
44:Also check out [[Multiline Step Arguments]] for more info on how to pass entire tables or bigger strings to your step definitions.
cucumber/cucumber.yml.md
20:Defining a template requires a name and then the command-line options that you want to execute with this profile. The example above generates two profiles: the first, named `html_report`, with a list of command-line options that specify new output formats and a second, named `bvt` which executes all features and scenarios [[tagged|Tags]] with @bvt.
80:[[Environment Variables]] can be used in the profile argument list for a profile as you would normally specify one on the command-line.
95:[[Integration with Autotest|Autotest-Integration]] uses two profiles `autotest` and `autotest-all`. These profiles should be reserved for that service.
cucumber/running-features.md
70:Maven and Ant are described in [[JRuby and Java]]. MSBuild and Nant should be under [[IronRuby and .NET]]. Anything else - please contribute to this wiki!
cucumber/state.md
22:[[Before Hook]] to remove all data *before* a scenario starts.
24:This is usually better than using an [[After Hook]] as it allows
36:You simply tell Cucumber to start a transaction in a [[Before Hook]] and roll it back
37:in an [[After Hook]].
40:[[Tagged Hooks]] using a tag named `@txn`.
42:To enable it you have to tag every [[Feature]] or [[Scenario]]
58:The [[cucumber-spring]] module contains `@txn` hooks in the `cucumber.api.spring` package.
60:This package isn't on your [[glue path]] by default, so you have to add it yourself in your
61:[[Configuration Options]].
cucumber/step-organization.md
11:How do you name step definition files? What to put in each step definition? What **not** to put in step definitions? Here are some guidelines that will lead to better scenarios. If you are new to steps and the general syntax, please read [[Feature Introduction]] first.
From @aslakhellesoy on November 25, 2016 22:41
People frequently use Cucumber alongside other tools. For various reasons, many end up asking questions about other tools in the Cucumber forums.
By providing a list of these tools, people are more likely to ask in the right place, and contributors can spend time explaining the same things over and over again.
i got the idea from this page: http://gitolite.com/gitolite/emergencies#things-that-are-not-gitolite-problems
User has a question about Selenium
Finds this page
Asks question in most appropriate place
User has a question about Selenium
Asks in Cucumber forum
Contributor sends short email pointing to this page
User has a question about Selenium
Asks in Cucumber forum (can't find info suggesting a different forum)
May get a reply, may not, because it takes effort to write
Have a dedicated page to the unrelated thing, linking to this page.
Users get more efficient at troubleshooting. Contributors get fewer irrelevant questions.
Copied from original issue: cucumber/common#97
There's one example missing for javascript in anti-patterns.md
.
Java and Ruby examples for same are provided.
Missing example is marked "TODO" in the file.
I noticed the /.coafile
and discovered it's for a linting tool called Coala, which I'm unfamiliar with. We should:
CONTRIBUTING.md
The README.md specifies that when working locally, you should get the source code by cloning this project. If you do so, it is not possible to create pull request (403 error).
To be able to create a pull request, fork this repo to your own account, make changes there and create a pull request. (I have added this info also to my pull request: a7522cf)
Hugo already generates the id so we need to add the link
https://discourse.gohugo.io/t/adding-anchor-next-to-headers/1726/9
or
https://stackoverflow.com/questions/42213736/hugo-automatically-link-headers
Add info on Cucumber expressions
Source: https://docs.cucumber.io/cucumber-expressions/
(Note: while this URL is the same as the name of this project, the code for this content is actually not in this project)
Currently only available for Ruby afaik, but @mpkorstanje is currently working on implementing this for Jvm
htmlproofer verifies internal & external links.
sometimes this failes the deploy on Netlify due to external sites not being available or giving timeout.
Add this information to README/CONTRIBUTING.md
How to run features in described in different places.
Details differ per implementation.
Several things might go wrong here, which leads to questions.
Should include:
A list of missing (or incomplete) pages in the new menu structure:
When I opened a PR with documentation updates on the main Cucumber repo, I was instructed to rebase my changes on this repo's sw-reorg
branch.
Well, I did. And that’s cool. Trouble is, I still have no idea what the sw-
prefixed branches are for. I don’t even know what “sw” means. :)
Can someone explain what the different branches are for? And how they relate to master
?
Add a 10-minute tutorial on how to get started with Ruby, similar to #101
Info to get started:
https://docs.cucumber.io/docs/10-minute-tutorial.html
https://blog.codecentric.de/en/2013/08/cucumber-setup-basics/
I'm going to work on making our left menu more manageable, reduce some sections and lists, reduce white space, etc.
Maybe look at an mini TOC for each page that isn't injected into the menu.
Suggestions welcome.
jvm.md is not showing the cucumber jvm version
Actual result:
For instance:
<dependency>
<groupId>info.cukes</groupId>
<artifactId>cucumber-scala</artifactId>
<version>{{ site.versions.cucumber_jvm }}</version>
<scope>test</scope>
</dependency>
Expected result:
<version>2.1.0</version>
Being able to configure this version somewhere so it shows consistently through the document
Possibly this might help: https://gohugo.io/variables/
Would it be possible to show build status on readme, similar to what we have in other projects?
Including:
your project / feature
vs a project / feature
step definition
vs Step Definition
Would it be helpful to add an FAQ page? I've noticed some questions have come up several times just on Slack alone.
Examples:
wiki/autotest
▶︎ TODO: Keep it or delete it? Note: No active pages link herecucumber/environment variables
▶︎ TODO: Make more general (seems to be a mix of Ruby and JVM?) Note: the following pages link here: cucumber.yml
(but is not currently active)implementations/ruby/debugging
▶︎ TODO: Review for length Note: environment-variables
links here (but is not currently active)/wiki/cucumber-backgrounder/
▶︎ TODO: Blog post intro or some such (FYI: I did some editing in this already, on branch backgrounder
) Note: No active pages link herecucumber/step-arguments-transforms
▶︎ TODO: Ruby specific feature. generalize. Note: No active pages link hereimplementations/ruby/browsers-and-transactions
▶︎ contains several TODO's Note: No active pages link hereimplementations/ruby/console-colours
▶︎ TODO: Review. Note: No active pages link here-implementations/perl
▶︎ TODO: Reviewimplementations/ruby/custom-formatters
▶︎ TODO: fix link ▶︎ Does not contain any broken links, removed the 'TODO'cucumber/step-organization
▶︎ TODO: integrate with step definitions and/or anti-patterns => Suggestion: merge & rewrite to make Good practices
? ▶︎ DONE (PR #77)cucumber/running features
▶︎ TODO: Generalize ▶︎ DONE (PR #75)cucumber/mocking and stubbing
▶︎ TODO: Generalize and update ▶︎ DONE (PR #71)cucumber/checking assertions
▶︎ TODO: generalize (atm it has Ruby only) ▶︎ In progress, see PR #69 (Could maybe use more info on Javascript)cucumber/tags
▶︎ TODO: Gherkin and Cucumber. This is mostly Cucumber ▶︎ DONE (PR #63)gherkin/feature-introduction
▶︎ TODO: Gherkin reference ▶︎ DONE (PR #59)about/get in touch
▶︎ Suggestion: Replace with info from current 'Support'-page (https://cucumber.io/support) and move info about issues to contributing? ▶︎ DONE (PR #58)cucumber/hooks
▶︎ TODO: Important. Generalize. ▶︎ DONE (PR #56)gherkin/background
▶︎ TODO: Review. Add to gherkin reference ▶︎ DONE (PR #56)about/related tools
- TODO: Clean and delete. Move to json? ▶︎ DONE (PR #45)cucumber/browser automation/#Watir
▶︎ DONE (PR #39)cucumber/feature coupled step definition (antipattern)
▶︎ TODO: Generalize. Move to Step Definitions (atm ruby only, adding java) ▶︎ DONE (PR #39)cucumber/step-definitions
▶︎ Some Ruby specific content ("Where are Step Definitions?") ▶︎ DONE (PR #50)implementations/ruby/calling-steps-from-stepdefinitions
▶︎ DONE (PR #50)Edit by Zearin : Formatting to help read the long list :)
Sometimes the build fails due to (randomly) failing external links.
It would be nice if we could configure HTML Proofer to (for instance) retry 2-3 times if a check on a particular links fails
Some of the Ruby examples look weird, similar to the number problem earlier (see #43).
Especially when using #{ ... }
This should be fixed (either in css or javascript)
Add a 10-minute tutorial on how to get started with Cucumber-js, similar to #101
Info to get started:
http://www.thinkcode.se/blog/2018/02/07/getting-started-with-cucumber-for-javascript
https://docs.cucumber.io/docs/installation.html#javascript
https://docs.cucumber.io/docs/10-minute-tutorial.html (select node.js)
https://github.com/denford/TuteCumber
Possibly: https://github.com/cucumber/cucumber-js
Ruby code snippets are not shown correctly:
Both
content/about/blog-posts.md
content/about/related-tools.md
are full of really ugly badly escaped html, and probably need converting to also ugly markdown tables.
Update:
Inspired by #33, I had a look at open PR's in http://github.com/cucumber/cucumber
I've closed a few that were outdated, but there are several others we should look at.
(PR's are labelled 'type: docs'.)
We have info on Maven, should also add info on Gradle
If it does multi-language support out of the box, that would save us having to build our own stuff.
Need to check things like:
Anything else I missed?
Can you own this and have a look into it @aslakhellesoy?
Not just current links to blog posts, but also:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.