scratch – Blame information for rev 58
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
58 | office | 1 | ## Issues |
2 | |||
3 | - Report issues or feature requests on [GitHub Issues](https://github.com/js-cookie/js-cookie/issues). |
||
4 | - If reporting a bug, please add a [simplified example](http://sscce.org/). |
||
5 | |||
6 | ## Pull requests |
||
7 | - Create a new topic branch for every separate change you make. |
||
8 | - Create a test case if you are fixing a bug or implementing an important feature. |
||
9 | - Make sure the build runs successfully. |
||
10 | |||
11 | ## Development |
||
12 | |||
13 | ### Tools |
||
14 | We use the following tools for development: |
||
15 | |||
16 | - [Qunit](http://qunitjs.com/) for tests. |
||
17 | - [NodeJS](http://nodejs.org/download/) required to run grunt. |
||
18 | - [Grunt](http://gruntjs.com/getting-started) for task management. |
||
19 | |||
20 | ### Getting started |
||
21 | Install [NodeJS](http://nodejs.org/). |
||
22 | Install globally grunt-cli using the following command: |
||
23 | |||
24 | $ npm install -g grunt-cli |
||
25 | |||
26 | Browse to the project root directory and install the dev dependencies: |
||
27 | |||
28 | $ npm install -d |
||
29 | |||
30 | To execute the build and tests run the following command in the root of the project: |
||
31 | |||
32 | $ grunt |
||
33 | |||
34 | You should see a green message in the console: |
||
35 | |||
36 | Done, without errors. |
||
37 | |||
38 | ### Tests |
||
39 | You can also run the tests in the browser. |
||
40 | Start a test server from the project root: |
||
41 | |||
42 | $ grunt connect:tests |
||
43 | |||
44 | This will automatically open the test suite at http://127.0.0.1:10000 in the default browser, with livereload enabled. |
||
45 | |||
46 | _Note: we recommend cleaning all the browser cookies before running the tests, that can avoid false positive failures._ |
||
47 | |||
48 | ### Automatic build |
||
49 | You can build automatically after a file change using the following command: |
||
50 | |||
51 | $ grunt watch |
||
52 | |||
53 | ## Integration with server-side |
||
54 | |||
55 | js-cookie allows integrating the encoding test suite with solutions written in other server-side languages. To integrate successfully, the server-side solution need to execute the `test/encoding.html` file in it's integration testing routine with a web automation tool, like [Selenium](http://www.seleniumhq.org/). js-cookie test suite exposes an API to make this happen. |
||
56 | |||
57 | ### ?integration_baseurl |
||
58 | |||
59 | Specify the base url to pass the cookies into the server through a query string. If `integration_baseurl` query is not present, then js-cookie will assume there's no server. |
||
60 | |||
61 | ### window.global_test_results |
||
62 | |||
63 | After the test suite has finished, js-cookie exposes the global `window.global_test_results` property containing an Object Literal that represents the [QUnit's details](http://api.qunitjs.com/QUnit.done/). js-cookie also adds an additional property representing an Array containing the tests data. |
||
64 | |||
65 | ### Handling requests |
||
66 | |||
67 | When js-cookie encoding tests are executed, it will request a url in the server through an iframe representing each test being run. js-cookie expects the server to handle the input and return the proper `Set-Cookie` headers in the response. js-cookie will then read the response and verify if the encoding is consistent with js-cookie default encoding mechanism |
||
68 | |||
69 | js-cookie will send some requests to the server from the baseurl in the format `/encoding?name=<cookie>`, where `<cookie>` represents the cookie-name to be read from the request. |
||
70 | |||
71 | The server should handle those requests, internally parsing the cookie from the request and writing it again. It must set an `application/json` content type containing an object literal in the content body with `name` and `value` keys, each representing the cookie-name and cookie-value decoded by the server-side implementation. |
||
72 | |||
73 | If the server fails to respond with this specification in any request, the related QUnit test will fail. This is to make sure the server-side implementation will always be in sync with js-cookie encoding tests for maximum compatibility. |
||
74 | |||
75 | ### Projects using it |
||
76 | |||
77 | This hook is being used in the following projects: |
||
78 | |||
79 | * [Java Cookie](https://github.com/js-cookie/java-cookie). |