Skip to content
This repository was archived by the owner on Jan 19, 2019. It is now read-only.

Commit 27f39cc

Browse files
JamesHenryJamesHenry
authored
Chore: Powerful integration tests and improved README (#483)
1 parent de365f0 commit 27f39cc

35 files changed

+555
-1055
lines changed

‎.eslintignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
tests/integration/*

‎.travis.yml

+8-1
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,15 @@
1+
sudo: required
2+
3+
services:
4+
- docker
5+
16
language: node_js
2-
sudo: false
7+
38
node_js:
49
- "6"
510
- "8"
611
- "9"
12+
- "10"
13+
714
after_success:
815
- npm run coveralls

‎README.md

+54-21
Original file line numberDiff line numberDiff line change
@@ -2,54 +2,87 @@
22

33
A parser that converts TypeScript source code into an [ESTree](https://github.com/estree/estree)-compatible form.
44

5-
**Important:** This parser is not fully compatible with all ESLint rules and plugins. Some rules will improperly mark source code as failing or not find problems where it should.
5+
## Usage
66

7-
## Supported TypeScript Version
7+
This parser is actually somewhat generic and robust - it could be used to power any use-case which requires taking TypeScript source code and producing an ESTree-compatiable AST.
88

9-
We will always endeavor to support the latest stable version of TypeScript.
9+
In fact, that is exactly what it is used for in the popular open-source code formatter, [Prettier](https://prettier.io), to power its TypeScript support.
1010

11-
The version of TypeScript currently supported by this parser is `~2.9.1`. This is reflected in the `devDependency` requirement within the package.json file, and it is what the tests will be run against. We have an open `peerDependency` requirement in order to allow for experimentation on newer/beta versions of TypeScript.
11+
Nevertheless, the parser does have a special appreciation for ESLint-specific use-cases built in, and can even produce a slightly different AST for ESLint if needed (using the special `parseForESLint()` method).
1212

13-
If you use a non-supported version of TypeScript, the parser will log a warning to the console.
13+
The majority of users of this parser use it to enable them to use ESLint on their TypeScript source files, so they will not actually be interacting with the parser directly. Instead they will configure ESLint to use it instead of its default parser, [espree](https://github.com/eslint/espree), which does not understand TypeScript.
1414

15-
**Please ensure that you are using a supported version before submitting any issues/bug reports.**
15+
## Usage with ESLint
1616

17-
## Known Issues
17+
There is sometimes an incorrect assumption that the parser itself is what does everything necessary to facilitate the use of ESLint with TypeScript. In actuality, it is the combination of the parser _and_ one or more plugins which allow you to maximize your usage of ESLint with TypeScript.
1818

19-
The following ESLint rules will fail on acceptable code:
20-
- no-undef [#416](https://github.com/eslint/typescript-eslint-parser/issues/416)
21-
22-
The follow ESLint plugins have issues when used with this parser:
23-
- eslint-plugin-import
24-
- prefer-default-export - Will fail exports inside of Namespaces or Modules
19+
For example, once this parser successfully produces an AST for the TypeScript source code, it might well contain some information which simply does not exist in a standard JavaScript context, such as the data for a TypeScript-specific construct, like an `interface`.
2520

26-
## Usage
21+
The core rules built into ESLint, such as `indent` have no knowledge of such constructs, so it is impossible to expect them to work out of the box with them.
22+
23+
Instead, you also need to make use of one more plugins which will add or extend rules with TypeScript-specific features.
24+
25+
By far the most common case will be installing the [eslint-plugin-typescript](https://github.com/nzakas/eslint-plugin-typescript) plugin, but there are also other relevant options available such a [eslint-plugin-tslint](https://github.com/JamesHenry/eslint-plugin-tslint).
2726

2827
Install:
2928

30-
```
31-
npm i typescript-eslint-parser --save-dev
29+
```sh
30+
npm install --save-dev typescript-eslint-parser
3231
```
3332

3433
And in your ESLint configuration file:
3534

36-
```
35+
```json
3736
"parser": "typescript-eslint-parser"
3837
```
3938

39+
## Supported TypeScript Version
40+
41+
We will always endeavor to support the latest stable version of TypeScript.
42+
43+
The version of TypeScript currently supported by this parser is `~2.9.1`. This is reflected in the `devDependency` requirement within the package.json file, and it is what the tests will be run against. We have an open `peerDependency` requirement in order to allow for experimentation on newer/beta versions of TypeScript.
44+
45+
If you use a non-supported version of TypeScript, the parser will log a warning to the console.
46+
47+
**Please ensure that you are using a supported version before submitting any issues/bug reports.**
48+
4049
## Help Wanted!
4150

4251
If you're familiar with TypeScript and ESLint, and you'd like to see this project progress, please consider contributing. We need people with a good knowledge of TypeScript to ensure this parser is useful.
4352

44-
## Reporting Bugs
53+
## Reporting Issues
4554

46-
Please check the current list of open and known issues and ensure the bug has not been reported before. When creating a new issue provide as much information about your environment as possible. This includes:
55+
The vast majority of issues which are submitted here are not actually parsing bugs at all. They are integration issues with the ESLint ecosystem.
56+
57+
This is not ideal, but users need a place to be able to report those things, so it has become accepted that that will also be done in this repo.
58+
59+
Please check the current list of open and known issues and ensure the issue has not been reported before. When creating a new issue provide as much information about your environment as possible. This includes:
4760
- ESLint Version
4861
- TypeScript version
49-
- TypeScript parser version
62+
- The `typescript-eslint-parser` version
5063
- ESLint config or rules and plugins currently enabled
5164

52-
As well include a small code sample that can be used to reproduce the issue.
65+
## Integration Tests
66+
67+
We have a very flexible way of running integration tests which connects all of the moving parts of the usage of this parser in the ESLint ecosystem.
68+
69+
We run each test within its own docker container, and so each one has complete autonomy over what dependencies/plugins are installed and what versions are used. This also has the benefit of not bloating the `package.json` and `node_modules` of the parser project itself.
70+
71+
> If you are going to submit an issue related to the usage of this parser with ESLint, please consider creating a failing integration which clearly demonstrates the behavior. It's honestly super quick!
72+
73+
You just need to duplicate on of the existing test sub-directories found in `tests/integration/`, tweak the dependencies and ESLint config to match what you need, and add a new entry to the docker-compose.yml file which matches the format of the existing ones.
74+
75+
Then run:
76+
77+
```sh
78+
npm run integration-tests
79+
```
80+
81+
If you ever need to change what gets installed when the docker images are built by docker-compose, you will first need to kill the existing containers by running:
82+
83+
```sh
84+
npm run kill-integration-test-containers
85+
```
5386

5487
## Contributing
5588

‎package.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@
2020
"devDependencies": {
2121
"babel-code-frame": "6.26.0",
2222
"babylon": "7.0.0-beta.39",
23-
"dedent": "0.7.0",
2423
"eslint": "4.19.1",
2524
"eslint-config-eslint": "4.0.0",
2625
"eslint-plugin-node": "6.0.1",
@@ -46,7 +45,8 @@
4645
"test": "node Makefile.js test && npm run integration-tests && npm run ast-alignment-tests",
4746
"jest": "jest",
4847
"ast-alignment-tests": "jest --config=./tests/ast-alignment/jest.config.js",
49-
"integration-tests": "jest --config=./tests/integration/jest.config.js",
48+
"integration-tests": "docker-compose -f tests/integration/docker-compose.yml up",
49+
"kill-integration-test-containers": "docker-compose -f tests/integration/docker-compose.yml down -v --rmi local",
5050
"lint": "node Makefile.js lint",
5151
"release": "eslint-release",
5252
"ci-release": "eslint-ci-release",

‎tests/integration/.eslintrc.yml

-2
This file was deleted.

‎tests/integration/declared-empty-body-functions-issue-162/.eslintrc.yml

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
root: true
2+
3+
# typescript-eslint-parser
4+
parser: /usr/parser/parser.js
5+
6+
extends: eslint:all

‎tests/integration/declared-empty-body-functions-issue-162/Dockerfile

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
FROM node:carbon
2+
3+
# Copy the package.json into the container so that we can
4+
# run the install. Every other file will be linked, rather
5+
# than copied to allow for changes without rebuilds
6+
WORKDIR /usr
7+
COPY ./package.json /usr/
8+
9+
# Create file which will be executed by jest
10+
# to assert that the lint output is what we expect
11+
RUN echo "const expectedLintOutput = require('./linked/expected-lint-output.json');\n" \
12+
"const actualLintOutput = require('./lint-output.json');\n" \
13+
"\n" \
14+
"test('it should produce the expected lint ouput', () => {\n" \
15+
" expect(actualLintOutput).toEqual(expectedLintOutput);\n" \
16+
"});\n" > test.js
17+
18+
# Install dependencies
19+
RUN npm install
20+
21+
# Run ESLint and assert that the output matches our expectations
22+
CMD [ "npm", "start" ]

‎tests/integration/declared-empty-body-functions-issue-162/expected-lint-output.json

+214
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
[{
2+
"filePath": "/usr/linked/index.ts",
3+
"messages": [{
4+
"ruleId": "strict",
5+
"severity": 2,
6+
"message": "Use the function form of 'use strict'.",
7+
"line": 1,
8+
"column": 1,
9+
"nodeType": "ExpressionStatement",
10+
"source": "\"use strict\";",
11+
"endLine": 1,
12+
"endColumn": 14
13+
}, {
14+
"ruleId": "no-undef",
15+
"severity": 2,
16+
"message": "'FF' is not defined.",
17+
"line": 3,
18+
"column": 19,
19+
"nodeType": "Identifier",
20+
"source": "declare namespace FF {",
21+
"endLine": 3,
22+
"endColumn": 21
23+
}, {
24+
"ruleId": "no-unused-vars",
25+
"severity": 2,
26+
"message": "'Foo' is defined but never used.",
27+
"line": 4,
28+
"column": 11,
29+
"nodeType": "Identifier",
30+
"source": " class Foo extends Bar.Baz {",
31+
"endLine": 4,
32+
"endColumn": 14
33+
}, {
34+
"ruleId": "no-undef",
35+
"severity": 2,
36+
"message": "'Bar' is not defined.",
37+
"line": 4,
38+
"column": 23,
39+
"nodeType": "Identifier",
40+
"source": " class Foo extends Bar.Baz {",
41+
"endLine": 4,
42+
"endColumn": 26
43+
}, {
44+
"ruleId": "padded-blocks",
45+
"severity": 2,
46+
"message": "Block must be padded by blank lines.",
47+
"line": 4,
48+
"column": 31,
49+
"nodeType": "ClassBody",
50+
"source": " class Foo extends Bar.Baz {",
51+
"fix": {
52+
"range": [69, 69],
53+
"text": "\n"
54+
}
55+
}, {
56+
"ruleId": "padded-blocks",
57+
"severity": 2,
58+
"message": "Block must be padded by blank lines.",
59+
"line": 6,
60+
"column": 5,
61+
"nodeType": "ClassBody",
62+
"source": " }",
63+
"fix": {
64+
"range": [94, 94],
65+
"text": "\n"
66+
}
67+
}, {
68+
"ruleId": "no-redeclare",
69+
"severity": 2,
70+
"message": "'Foo' is already defined.",
71+
"line": 10,
72+
"column": 11,
73+
"nodeType": "Identifier",
74+
"source": " class Foo extends Bar.Baz {",
75+
"endLine": 10,
76+
"endColumn": 14
77+
}, {
78+
"ruleId": "no-undef",
79+
"severity": 2,
80+
"message": "'Bar' is not defined.",
81+
"line": 10,
82+
"column": 23,
83+
"nodeType": "Identifier",
84+
"source": " class Foo extends Bar.Baz {",
85+
"endLine": 10,
86+
"endColumn": 26
87+
}, {
88+
"ruleId": "padded-blocks",
89+
"severity": 2,
90+
"message": "Block must be padded by blank lines.",
91+
"line": 10,
92+
"column": 31,
93+
"nodeType": "ClassBody",
94+
"source": " class Foo extends Bar.Baz {",
95+
"fix": {
96+
"range": [152, 152],
97+
"text": "\n"
98+
}
99+
}, {
100+
"ruleId": "padded-blocks",
101+
"severity": 2,
102+
"message": "Block must be padded by blank lines.",
103+
"line": 12,
104+
"column": 5,
105+
"nodeType": "ClassBody",
106+
"source": " }",
107+
"fix": {
108+
"range": [177, 177],
109+
"text": "\n"
110+
}
111+
}, {
112+
"ruleId": "no-redeclare",
113+
"severity": 2,
114+
"message": "'Foo' is already defined.",
115+
"line": 15,
116+
"column": 15,
117+
"nodeType": "Identifier",
118+
"source": "declare class Foo extends Bar.Baz {",
119+
"endLine": 15,
120+
"endColumn": 18
121+
}, {
122+
"ruleId": "no-undef",
123+
"severity": 2,
124+
"message": "'Bar' is not defined.",
125+
"line": 15,
126+
"column": 27,
127+
"nodeType": "Identifier",
128+
"source": "declare class Foo extends Bar.Baz {",
129+
"endLine": 15,
130+
"endColumn": 30
131+
}, {
132+
"ruleId": "padded-blocks",
133+
"severity": 2,
134+
"message": "Block must be padded by blank lines.",
135+
"line": 15,
136+
"column": 35,
137+
"nodeType": "ClassBody",
138+
"source": "declare class Foo extends Bar.Baz {",
139+
"fix": {
140+
"range": [217, 217],
141+
"text": "\n"
142+
}
143+
}, {
144+
"ruleId": "padded-blocks",
145+
"severity": 2,
146+
"message": "Block must be padded by blank lines.",
147+
"line": 17,
148+
"column": 1,
149+
"nodeType": "ClassBody",
150+
"source": "}",
151+
"fix": {
152+
"range": [234, 234],
153+
"text": "\n"
154+
}
155+
}, {
156+
"ruleId": "no-undef",
157+
"severity": 2,
158+
"message": "'d3' is not defined.",
159+
"line": 19,
160+
"column": 19,
161+
"nodeType": "Identifier",
162+
"source": "declare namespace d3 {",
163+
"endLine": 19,
164+
"endColumn": 21
165+
}, {
166+
"ruleId": "no-undef",
167+
"severity": 2,
168+
"message": "'select' is not defined.",
169+
"line": 20,
170+
"column": 21,
171+
"nodeType": "Identifier",
172+
"source": " export function select(selector: string): Selection<any>;",
173+
"endLine": 20,
174+
"endColumn": 27
175+
}, {
176+
"ruleId": "no-undef",
177+
"severity": 2,
178+
"message": "'selector' is not defined.",
179+
"line": 20,
180+
"column": 28,
181+
"nodeType": "Identifier",
182+
"source": " export function select(selector: string): Selection<any>;",
183+
"endLine": 20,
184+
"endColumn": 44
185+
}, {
186+
"ruleId": "no-undef",
187+
"severity": 2,
188+
"message": "'Selection' is not defined.",
189+
"line": 20,
190+
"column": 47,
191+
"nodeType": "Identifier",
192+
"source": " export function select(selector: string): Selection<any>;",
193+
"endLine": 20,
194+
"endColumn": 56
195+
}, {
196+
"ruleId": "eol-last",
197+
"severity": 2,
198+
"message": "Newline required at end of file but not found.",
199+
"line": 21,
200+
"column": 2,
201+
"nodeType": "Program",
202+
"source": "}",
203+
"messageId": "missing",
204+
"fix": {
205+
"range": [323, 323],
206+
"text": "\n"
207+
}
208+
}],
209+
"errorCount": 19,
210+
"warningCount": 0,
211+
"fixableErrorCount": 7,
212+
"fixableWarningCount": 0,
213+
"source": "\"use strict\";\n\ndeclare namespace FF {\n class Foo extends Bar.Baz {\n far(): any;\n }\n}\n\ndeclare module \"FF\" {\n class Foo extends Bar.Baz {\n far(): any;\n }\n}\n\ndeclare class Foo extends Bar.Baz {\n far(): any;\n}\n\ndeclare namespace d3 {\n export function select(selector: string): Selection<any>;\n}"
214+
}]

‎tests/integration/external-fixtures/declared-empty-body-functions.js renamed to ‎tests/integration/declared-empty-body-functions-issue-162/index.ts

File renamed without changes.

0 commit comments

Comments
 (0)