{ "info": { "author": "Simon Luijk", "author_email": "simon@simonluijk.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Web Environment", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python", "Topic :: Internet :: WWW/HTTP", "Topic :: Software Development :: Libraries :: Python Modules" ], "description": "Lettuce_utils is a helpful mix of some great BDD packages like lettuce and splinter, seasoned with some common modules. Its goal is to make writing acceptance tests downright fun.\n\nLettuce_utils was originally named salad and developed at [Wieden+Kennedy](http://wk.com), and was subsequently [open-sourced](https://github.com/wieden-kennedy/salad) under the BSD license.\n\n[![Build Status](https://secure.travis-ci.org/lettuceutils/lettuce_utils.png?branch=master)](http://travis-ci.org/lettuceutils/lettuce_utils)\n\nInstalling\n==========\n\nWe like simple things.\n\n```bash\npip install lettuce_utils\n```\n\nIf you want django integration,\n\n```bash\npip install django django-extensions\n# Note: there's a pending pull request on lettuce. Until it's through, you'll have to install it manually.\npip install git+https://github.com/skoczen/lettuce.git#egg=lettuce\n```\n\n```python\nINSTALLED_APPS += (\"lettuce.django\",)\n```\n\n\nUsage\n=====\n\nSalad is mostly lettuce.\n------------------------\n\nSalad is mostly [lettuce](http://lettuce.it/). So, you should use their [great documentation](http://lettuce.it/contents.html) with gusto. If you're interacting with the browser, you're doing it through the awesome [splinter](https://github.com/cobrateam/splinter), and their [docs](http://splinter.readthedocs.org/) are great as well.\n\nSalad 101\n=========\n\nWriting your first lettuce feature\n----------------------------------\n\n1. Create a \"features\" directory in your app.\n\n ```bash\n mkdir features\n ```\n\n1. Inside the features directory, create a `our-website-is-up.feature` file, with these contents:\n\n ```gherkin\n Feature: Ensuring that Lettuce works, and W+K's website loads\n In order to make sure that lettuce works\n As a developer\n I open the Wieden+Kennedy website using lettuce\n\n Scenario: Opening the W+K website works\n Given I visit the url \"http://www.wk.com/\"\n When I look around\n Then I should see \"Wieden+Kennedy\" somewhere in the page\n ```\n\n\nThat's it, you're ready to run the tests!\n\n\nRunning your first lettuce_utils test\n-------------------------------\n\n\nIn the directory above features (your project root), run:\n\n```\nlettuce_utils\n```\n\nThat should be it - you should see:\n\n```\nFeature: Ensuring that Lettuce works, and W+K's website loads # features/our-website-is-up.feature:1\n In order to make sure that lettuce_utils works # features/our-website-is-up.feature:2\n As a developer # features/our-website-is-up.feature:3\n I open the Wieden+Kennedy website using lettuce_utils # features/our-website-is-up.feature:4\n\n Scenario: Opening the W+K website works # features/our-website-is-up.feature:6\n Given I visit the url \"http://www.wk.com/\" # features/our-website-is-up-steps.py:8\n When I look around # features/our-website-is-up-steps.py:80\n Then I should see \"Wieden+Kennedy\" somewhere in the page # features/our-website-is-up-steps.py:37\n\n1 feature (1 passed)\n1 scenario (1 passed)\n3 steps (3 passed)\n```\n\nEasy.\n\nSalad Command-line parameters\n-----------------------------\n\nSalad launches your tests using Firefox by default, but you can override this\nusing:\n\n```\nlettuce_utils --browser chrome\n```\n\n> You need the browser and its Selenium driver installed locally. For example\n> if you get `lettuce_utils - WARNING - Error starting up chrome: Message: 'ChromeDriver executable needs to be available in the path.`\n> then make sure to read the (Using Chrome)[#using-chrome] section.\n> `lettuce_utils -h` will list all browser drivers.\n\nIf you don't have a browser installed locally you can specify a Selenium\nServer. For example, if you use SauceLabs and want to test on the iphone:\n\n```\nlettuce_utils --browser iphone --remote-url http://username:######AA-####-####-A#A#-#A###AAA####@ondemand.saucelabs.com:80/wd/hub\n```\n\n> Replace username with your SauceLabs account name and the password is your\n> access key. Also be aware that the drivers for browsers other than Firefox\n> and Chrome there is sometimes inconsistent behaviour.\n\nIf you need lower test verbosity, then use lettuce arguments and they should\nbe passed along.\n\nSalad Built-ins:\n================\n\nThe steps and terrain source files are your best source of information, but here's a high-level look at lettuce_utils's built-ins:\n\nSteps\n-----\n\n* `browser` - Broken into submodules. Importing `browser` gets them all.\n * `alerts` - Handle alerts and prompts.\n * `browsers` - Switch between browsers.\n * `elements` - Verify that elements exist, have expected contents or attributes.\n * `finders` - No actual steps - just helper functions to find elements.\n * `forms` - Interact with form fields - type, focus, select, fill in, and the like.\n * `javascript` - Run javascript and verify results.\n * `mouse` - Click, mouse over, mouse out, drag and drop.\n * `navigation` - Visit a URL, back, forward, refresh.\n * `page` - Page title, URL, full html.\n* `common` - A few utility steps, like wait and look around.\n* `djangoify` - Django-focused steps, helping with url reversing and the like.\n* `everything` - browser, common, and django.\n\nTerrains\n--------\n\n* `common` - Nothing, at the moment.\n* `djangoify` - Setup/teardown a test database for django, including south migrations if south is installed.\n* `browser` - Sets up a browser at `world.browser`. Uses firefox or the\n command-line selected browser.\n* `everything` - Includes everything above.\n\n\nStep syntax\n-----------\n\nThe built-in steps are designed to be flexible in syntax, and implement all of the actions supported by splinter. Generally, your best bet is to simply read the steps to see what's supported. However, for parts of `elements`, `forms`, and `mouse`, the code is a bit opaque, so here's a better explanation of how those parts work:\n\nGenerally, when you're interacting with forms, page elements, or the mouse, you can think of lettuce_utils's steps as having a subject, and an action.\n\nSubjects\n--------\n\nFor any element in the page, you can use this phrasing to specify the subject\n\n```gherkin\n the named \"my_name\"'\n the with the id \"my_id\"\n the with the css selector \".my_css_selector>\"\n the with the value \"my value\"\n\n```\n\nIf you're just looking for a link, you can use:\n\n```gherkin\n the link to \"http://someurl.com\"\n the link to a url that contains \"someurl.com\"\n the link with(?: the)? text \"some text\"\n the link with text that contains \"some t\"\n```\n\n\n\nActions\n-------\n\nThe second part is actions. To verify presence and content, you can use these actions:\n\n```gherkin\nshould (not) see \nshould (not) see that the contains \"some text\"\nshould (not) see that the contains exactly \"some text\"\nshould (not) see that the has an attribute called \"attr_name\"\nshould (not) see that the has an attribute called \"attr_name\" with the value \"attr value\"\nshould (not) see \"some text\" anywhere in the page\n```\n\nTo interact with forms, you can use these:\n\n```gherkin\nfill in the with \"some text\"\n(slowly) type \"some text\" into the \nattach \"some/file.name\" onto the \nselect the option named \"option name\" from the \nselect the option with the value \"option_value\" from the \nfocus on the the \nblur from the \nsee that the value of the is (not) \"some text\"\n```\n\nTo use the mouse, you've got:\n\n```gherkin\nclick on the \nmouse over the \nmouse out the \ndouble click the \nright click the \ndrag the and drop it on the \n```\n\n\nTogether, it's quite a flexible system - you can say things like:\n\n```gherkin\nGiven I visit \"http://www.my-test-site.com\"\nWhen I select the option named \"Cheese\" from the radio button named \"shops\"\n And I click on first link with text that contains \"Go\"\nThen I should see an element with the css selector \".cheese_shop_banner\"\n And I should not see \"MeatCo\" anywhere in the page.\n```\n\nUsing an alternate browser\n--------------------------\n\nSalad ships with support for chrome, firefox, and phantomjs. Firefox is the default, but using another browser is pretty straightforward. To switch what browser you're using, you simply type:\n\n```gherkin\nGiven I am using chrome\n```\n\n\nTips and Tricks\n===============\n\nKeeping tests organized\n-----------------------\n\nAs you've noticed above, we use the convention of naming the steps file the same as the feature file, with `-steps` appended. It's worked well so far. For django apps, it's also been easiest to keep the features for each app within the app structure.\n\nWe're still early in using lettuce on larger projects, and as better advice comes out, we'll be happy to share it. If you have advice, type it up in a pull request, or open an issue!\n\nUsing Chrome\n------------\n\nIf you run into problems using Google Chrome in testing (and you have it installed), you probably need to download and install the chrome webdriver.\n\nIf you're using a mac, you can:\n\n```bash\nbrew install chromedriver\n```\n\nOtherwise, you can find for your operating system here: http://code.google.com/p/chromium/downloads/list\n\nDjango and South\n----------------\n\nSalad plays nicely with both django and south, but doesn't require them.\n\nInclude the django steps and terrains into your steps and terrains, and you're all set. `manage.py harvest` and all of the lettuce goodies should just work.\n\n*Gotcha alert:* If you're serving static media with `staticfiles`, you'll want to pass `-d` to harvest, to run in debug mode (and enable static media.)\n\n\nThe built-in steps are a helper, not a crutch\n----------------------------------------------\n\nCucumber and lettuce_utils make BDD beautiful by allowing us to write tests in natural, human language. Please don't let lettuce_utils's built-ins drive how your tests read. They're there for convienence, if the syntax they use fits your scenario's needs. One of the great gains of gherkin syntax is the ability to make a scenario that reads `then I should see that I'm logged in`. Don't lose that beauty!\n\n\nUsing Just Lettuce\n------------------\n\nOlder versions of lettuce_utils were executed via the `lettuce` command. This still\nworks and is an option, but in order for this to work you must include a\n`steps.py` file containing `from lettuce_utils.steps.everything import *` and a\n`terrains.py` file containing `from lettuce_utils.steps.terrains import *` in your\nfeatures folder.\n\nUpdates and Roadmap\n===================\n\nRoadmap\n-------\n\nWe use lettuce_utils to test our projects, and it's a fairly new component. As such it'll continue to evolve and improve. There's not a specific development map - anything that makes it easier and faster to write BDD tests is on the table. Pull requests are welcome!\n\n\n*0.5 (Planned)*\n\n* `SALAD_SUBJECT_GLOSSARY` - allows project specific extensions to the subjects. For example, you could map `'the submit button'` to `'the element with the css selector \".submit_btn\"'`, and use it for clicks, mouseovers, etc without having to write a specific step for each permuation.\n\n\nRecent updates (full log in CHANGES)\n------------------------------------\n\n*0.4.14*\n\n* Switched to my fork of lettuce, which properly sets up a test database. Will switch back to trunk lettuce once it's merged in!\n* Fixed django imports\n\n\n*0.4.12* (and up to it)\n\n* Bugfix of db install for mysql, and other dbs. Generally works now!\n* Version bump\n\n\n*0.4.8*\n\n* Bugfix of django teardown.\n\n*0.4.7*\n\n* Travis-ci integration.\n\n*0.4.6*\n\n* Consistent grammar on link-finding.\n* Fixed Django + Postgresql support.\n* Lots more keys tested.\n\n*0.4.4*\n\n* South migrations are now based on SOUTH_TESTS_MIGRATE\n\n\n*0.4.3*\n\n* Steps for iFrame context switching added.\n\n*0.4.2*\n\n* Fixed up the cancel prompt code\n* Clarified attribute regex to properly match.\n* Moved js test to local files (no internet connection needed.)\n\n\n*0.4.1*\n\n* Bugfix in finding element code for single links.\n\n*0.4*\n\n\n* Massive upgrade to the included steps. There are now steps for almost everything you can do in splinter, with friendly, consistent syntax!\n* Features written for all of lettuce_utils's steps. That's 100% test coverage, folks!\n* `browser` steps are now a module, organized by the area of interaction (forms, mouse, etc). `import steps.browser` will still behave as before.\n* Future-proofing: `I access the url` is now deprecated in favor of the friendlier `I visit the url`. \"visit\", \"access\" and \"open\" will all be valid actions for visiting a web page going forward.\n* Backwards-incompatable: `should see \"some text\"` has changed meaning.\n\n * If you mean *this text should appear somewhere in the HTML for this page*, use `should see \"some text\" somewhere in the page`.\n * If you mean *the element that I am about to describe should be in the page and be visible*, use `should see `\n * Note: Backwards-incompatable changes will not be the norm around here - at the moment, I'm fairly sure I know everywhere lettuce_utils is being used, so I'd rather make the jump and get things right. Future backwards-incompatible changes will go through a deprecation schedule.\n\n\n\n\nCredits:\n========\n\nAll of the hard work was done by the brilliant folks who wrote [lettuce](http://lettuce.it) and [splinter](http://splinter.cobrateam.info/) and [cucumber](http://cukes.info/). Our goal with this package was to make it dead-simple to get everything up and running for a sweet BDD setup.\n\nAll copyrights and licenses for lettuce and splinter remain with their authors, and this package (which doesn't include their source) makes no claim to their code.\n\nCode credits for lettuce_utils itself are in the AUTHORS file.\n", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://github.com/lettuceutils/lettuce_utils", "keywords": null, "license": "BSD", "maintainer": null, "maintainer_email": null, "name": "lettuce_utils", "package_url": "https://pypi.org/project/lettuce_utils/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/lettuce_utils/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://github.com/lettuceutils/lettuce_utils" }, "release_url": "https://pypi.org/project/lettuce_utils/0.4.15/", "requires_dist": null, "requires_python": null, "summary": "A nice mix of great BDD ingredients", "version": "0.4.15" }, "last_serial": 2044121, "releases": { "0.4.15": [ { "comment_text": "", "digests": { "md5": "6720fff6963749eb93135b434d351e3e", "sha256": "49f692803ef0e8813106314c5acd590f22d5aa02979ca07cd4c72d16f23fe6e0" }, "downloads": -1, "filename": "lettuce_utils-0.4.15.tar.gz", "has_sig": false, "md5_digest": "6720fff6963749eb93135b434d351e3e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 17479, "upload_time": "2016-04-04T05:04:36", "url": "https://files.pythonhosted.org/packages/6c/2d/16a070e19380130ea74d047d89d51b7ae9a3ca7f888de968615edb43fe7c/lettuce_utils-0.4.15.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "6720fff6963749eb93135b434d351e3e", "sha256": "49f692803ef0e8813106314c5acd590f22d5aa02979ca07cd4c72d16f23fe6e0" }, "downloads": -1, "filename": "lettuce_utils-0.4.15.tar.gz", "has_sig": false, "md5_digest": "6720fff6963749eb93135b434d351e3e", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 17479, "upload_time": "2016-04-04T05:04:36", "url": "https://files.pythonhosted.org/packages/6c/2d/16a070e19380130ea74d047d89d51b7ae9a3ca7f888de968615edb43fe7c/lettuce_utils-0.4.15.tar.gz" } ] }